---
title: "Create Temporary Credential"
method: POST
path: "/api/temporary-credentials"
tags: ["Temporary Credentials"]
---

# Create Temporary Credential

`POST /api/temporary-credentials`

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.

## Headers

- `X-Polytomic-Version` string

## Request body

- CreateTemporaryCredentialRequest
  - `duration_seconds` integer, nullable — Credential lifetime in seconds. Defaults to 3600 (1 hour); minimum 600 and maximum 14400.
  - `session_name` string — Optional audit correlation label, limited to 128 characters. Do not include secrets or personal data.
  - `subject` TemporaryCredentialSubject, required
    - `mode` 'user' | 'read_only' — Authority mode for a user credential. Defaults to user. Profile subjects do not accept this field.
    - `organization_id` string, uuid — Target organization for broker-issued credentials. Omit when the caller's organization determines the target.
    - `profile_id` string, uuid — Target Agent Data profile for a profile credential.
    - `type` 'user' | 'profile', required — Authority subject type. Use user for current user authority or profile for an Agent Data profile.
    - `user_id` string, uuid — Target user for broker-issued user credentials. Omit for user self-issuance.

## Response `200`

OK

- TemporaryCredentialResponseEnvelope
  - `data` TemporaryCredentialResponse
    - `access_token` string — Temporary credential secret. This value is returned only once; store it securely.
    - `expires_at` string, date-time — Timestamp after which the credential is rejected.
    - `id` string, uuid — Temporary credential identifier used for usage attribution.
    - `token_type` string — Authorization scheme for the access token. Always Bearer.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `429` — Too Many Requests
- `500` — Internal Server Error

---

[API](https://skmtc.net/polytomic/apis/polytomic-api.md) · [All operations](https://skmtc.net/polytomic/apis/polytomic-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/polytomic/polytomic-api/revisions/31d9a913d396/schema)