manage-credentials

name	manage-credentials
description	Set up and manage package and connection credentials securely
when-to-use	When user asks about credentials, secrets, API keys, or connection authentication
effort	low

Manage Credentials

Help the user store, retrieve, and manage security credentials for packages and database connections.

Usage

/manage-credentials [package-name] [--connection <connection-name>]

Instructions

1. Read package credentials in code

const creds = await _package.getCredentials();
if (creds === null) {
  grok.shell.info('Credentials are not set.');
  return;
}
const login = creds.parameters['login'];
const password = creds.parameters['password'];

Read a single parameter:

const creds = await _package.getCredentials();
const apiKey = creds.parameters['apiKey'];

2. Set package credentials via API

Send a POST request to the credentials endpoint:

const grokHost = 'https://your-instance.datagrok.ai';
const packageName = 'MyPackage';
const url = `${grokHost}/api/credentials/for/${packageName}`;

const headers = {
  'Authorization': apiKey,
  'Content-Type': 'application/json'
};

const credentials = {login: 'myLogin', password: 'myPassword'};
await fetch(url, {method: 'POST', headers, body: JSON.stringify(credentials)});

3. Set package credentials via UI

1. Go to Manage | Packages
2. Right-click the package > Credentials...
3. Add key-value pairs
4. Set Credentials owner (a user or group — only members can read)

4. Connection credentials in JSON

Define credentials in the connection JSON file using environment variable substitution:

{
  "#type": "DataConnection",
  "name": "MyDb",
  "parameters": {
    "server": "db.example.com",
    "port": 5432,
    "db": "mydb"
  },
  "credentials": {
    "parameters": {
      "login": "${DB_LOGIN}",
      "password": "${DB_PASSWORD}"
    }
  },
  "dataSource": "Postgres"
}

5. Set connection credentials via API

For connections that belong to a package, use a dotted name:

POST ${GROK_HOST}/api/credentials/for/${PACKAGE_NAME}.${CONNECTION_NAME}
Headers: { Authorization: <API_KEY>, Content-Type: application/json }
Body: { "login": "...", "password": "..." }

6. Service users

For automated credential management, create a service user:

1. Go to Manage | Users | Actions | Add Service User
2. Specify a login and generate an API key
3. Use the service user's API key for programmatic credential setup

Behavior

• Never commit credentials or secrets in JSON files to the repository.
• Always use environment variable substitution (${VAR_NAME}) in connection files for sensitive values.
• When the user needs to store API keys or tokens, guide them to package credentials (_package.getCredentials()).
• When the user needs database login/password, guide them to connection credentials.
• Remind users about the Credentials owner field — it controls who can read the credentials.
• For examples, refer to the NLP package and packages/ApiSamples/scripts/misc/package-credentials.