Credentials API

This page is for developers who want to manage credentials from their own code. A credential is a key, token or account sign-in almyty keeps safely on your behalf, such as the key to your order system or your Slack app’s secrets. For example, a script can check every credential’s health each morning. In the app, this is Credentials; for the concepts, see Credentials and Who can use a credential.

REST reference for credentials and the services they are added for. Responses never contain a secret value: a credential added for a service is returned as its account label, health, scopes, method and owner; a key an API, MCP server, channel or app keeps for itself is returned masked.

Endpoints

connections:read belongs to every role, connections:manage to admins and owners; an Enterprise custom role can carry either.

The OAuth 2.0 sign-in an API’s description declares runs under /credentials/oauth2/* (authorize, callback, client credentials) and makes a credential of the oauth2 service, which renews itself with its refresh token.

Add a credential

curl -X POST https://api.almyty.com/credentials/connect/openai \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "owner": "org", "input": { "apiKey": "sk-..." } }'

A form method is checked live and answers { pending: false, connection }. A sign-in method answers { pending: true, authorizeUrl, state, completeWith }; the browser finishes at the callback, or the terminal posts { state, code } to /complete.

Two services cover what any API may ask for:

Response

{
  "success": true,
  "data": {
    "pending": false,
    "connection": {
      "id": "c3a9...",
      "connectorKey": "openai",
      "name": "OpenAI",
      "method": "api_key",
      "owner": "org",
      "accountLabel": "...k3Fz",
      "health": { "status": "valid", "checkedAt": "2026-09-08T09:00:00Z", "error": null },
      "scopesGranted": []
    }
  }
}

A credential that fails its check answers 422 CONNECTION_VALIDATION_FAILED with the service’s error and the credential, kept with health failed, so it can be checked again or its key replaced without starting over.

Custom service

curl -X POST https://api.almyty.com/credentials/services \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "lab-vllm",
    "kind": "inference",
    "displayName": "Lab vLLM",
    "connect": [{
      "type": "api_key",
      "label": "Endpoint and key",
      "schema": {
        "type": "object",
        "properties": {
          "baseUrl": { "type": "string", "format": "uri" },
          "apiKey": { "type": "string", "x-secret": true }
        },
        "required": ["baseUrl"]
      }
    }],
    "validation": { "kind": "http", "url": "{{baseUrl}}/models", "method": "GET", "auth": "bearer" }
  }'

Kinds: inference, deployment, memory, mcp, tool_source, channel, cloud, registry. Validation kinds: http, format, aws_caller_identity, aws_assume_role, gcp_service_account, oauth2_client_credentials, s3_bucket, mcp_initialize.

Grants

Who may use a credential beyond its owner. The rules are on Who can use a credential; the routes only check membership (connections:read), and whether the caller may manage this particular credential is decided per request.

curl -X POST https://api.almyty.com/credentials/c3a9.../grants \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "principalType": "agent", "principalId": "a1b2...", "permission": "use", "expiresAt": "2026-12-31T00:00:00Z" }'

A grant is returned as { id, connectionId, principalType, principalId, permission, budgetId, grantedBy, createdAt, expiresAt, expired }.

Grant errors: CONNECTION_GRANT_FORBIDDEN, GRANT_NOT_FOUND, GRANT_PRINCIPAL_INVALID, GRANT_PRINCIPAL_NOT_FOUND, GRANT_AGENT_NOT_OWNED, GRANT_WORKSPACE_NOT_OWNED, GRANT_PERMISSION_INVALID, GRANT_EXPIRES_INVALID, GRANT_EXPIRES_IN_PAST, GRANT_BUDGET_NOT_FOUND. A run refused a credential fails with 403 CONNECTION_NOT_GRANTED and a reason. Granting and revoking write connection_grant and connection_revoke_grant; every use writes connection_resolve with the principal, run, purpose and how the decision was reached.

Governance (Enterprise)

With the credentials_governance entitlement, /ee/credentials/* adds policy rules, the review of personal credentials, expiry and scheduled rotation, and the audit export. See Enterprise.

Error codes

CONNECTOR_UNKNOWN, CONNECT_METHOD_UNSUPPORTED, CONNECT_INPUT_INVALID, CONNECTIONS_PERMISSION_REQUIRED, NOT_A_MEMBER, USER_CONNECTIONS_DISABLED, CONNECT_STATE_INVALID, CONNECT_EXCHANGE_FAILED, CONNECT_DENIED, CONNECT_CLIENT_NOT_CONFIGURED, CONNECTION_VALIDATION_FAILED, CONNECTION_NOT_FOUND, CONNECTION_FORBIDDEN, CONNECTION_INACTIVE, CONNECTOR_INVALID, CONNECTOR_KEY_TAKEN.

Audit actions

connection_connect, connection_validate, connection_rotate, connection_disconnect, connection_resolve, connector_create, on resource connection or connector, with the service key, method, owner and outcome in the details.