v1

latestOpenAPI 3.0.32026-08-06138294578.6 KB

Temporary Credentials

Create Temporary Credential

Issues a non-renewable credential with a bounded lifetime for a user or Agent Data profile.

The response contains the credential secret once. Store it securely and send it as a Bearer token in the Authorization header.

Set subject.type to user to issue a credential for your authenticated user. Omit organization_id and user_id; Polytomic derives both values from your credential. Set mode to read_only to limit the credential to the intersection of the user's current permissions and read-only actions. A read-only caller can issue only read-only credentials.

Partner callers must provide both organization_id and user_id. The target must be an active user in an organization owned by the partner. User subjects must be application users; Agent Data portal-only users continue to use profile credentials.

User credentials resolve the subject's current permissions on every request. Permission changes take effect immediately, and deleting the user invalidates the credential.

Set subject.type to profile and provide the Agent Data profile ID. The credential uses the profile's current connection access on every request; changes take effect immediately, and deleting the profile invalidates the credential.

A temporary credential stops authenticating at expires_at. It cannot be refreshed, extended, or used to create another temporary credential. Create a new credential with a durable authorized credential when you need a later expiration.

Each organization may have up to 1,000 active temporary credentials. The endpoint returns 429 Too Many Requests at the limit. Expired credentials stop counting toward the limit immediately, before periodic cleanup removes them.

⚠️ Session names are audit labels

Use session_name only for non-sensitive job or agent-session correlation. Do not include secrets or personal data.

Polytomic periodically removes expired credential records. API usage history keeps its credential ID according to the normal API usage retention period.

post/api/temporary-credentials

Headers

X-Polytomic-Versionstring

Request body

duration_secondsinteger nullable

Credential lifetime in seconds. Defaults to 3600 (1 hour); minimum 600 and maximum 14400.

session_namestring

Optional audit correlation label, limited to 128 characters. Do not include secrets or personal data.

Example request

{
  "subject": {
    "organization_id": "248df4b7-aa70-47b8-a036-33ac447e668d",
    "profile_id": "248df4b7-aa70-47b8-a036-33ac447e668d",
    "user_id": "248df4b7-aa70-47b8-a036-33ac447e668d"
  }
}

Response

Example response

{
  "data": {
    "id": "248df4b7-aa70-47b8-a036-33ac447e668d"
  }
}