Lifecycle & API keys

The AI clients page in the portal contains connection URLs for interactive OAuth clients and API keys for advanced or headless clients.

Prefer OAuth

Use OAuth when the client supports it. OAuth keeps the user and workspace selection visible during authorization and avoids copying a long-lived secret.

After connecting:

Confirm the selected Stackyapper workspace.
Ask the client to list or inspect available tools.
Run one small read-only request.
Confirm the call and client name in Audit.

OAuth lifetimes

Credential	Lifetime
OAuth access token	1 hour, renewed automatically with a rotating refresh token
Authorization grant	Up to 90 days, then the user must authorize the client again

Deployments and temporary connection interruptions do not reset an authorization.

API keys

Create an API client only when the software cannot complete the supported OAuth flow.

Give the client a name that identifies its owner and purpose, such as service-desk-codex or reporting-runner.

The full key is displayed once. Copy it directly into the intended client's secret store. Do not put it in chat, tickets, source control, screenshots, or shared notes.

The AI clients page shows whether an API client has never been used or when it was last used. Treat an unexpectedly unused or active client as a reason to verify its configuration and owner.

API key properties

Property	Behavior
Format	`sk_live_` followed by 64 hex characters
Visibility	Plaintext shown exactly once at creation; the list shows only the first 12 characters afterward
Storage	Only a SHA-256 hash is stored; a lost key cannot be recovered, only replaced
Expiry	Keys never expire; only revocation ends them
Scope	One user in one workspace; the key stops working if that membership is removed or the workspace is not active
Active keys	One active key per user — creating a new key automatically revokes the previous one
Who can create	Any signed-in member can create their own key; MSP-delegated sessions cannot, and the workspace's AI client admission policy can disable API-key clients entirely
Revocation	Self-service delete in the portal; keys are also revoked automatically when the member is removed from the workspace

Because keys never expire, rotate them on your own schedule: create a new key (which revokes the old one) and update the intended client immediately.

Revoke or rotate

Revoke a client when:

A device is lost or reassigned.
A key may have been copied to the wrong system.
A user or automation no longer needs access.
The client name or ownership cannot be established.

For API keys, rotation is create-then-update: creating a new key automatically revokes your previous one, so update the intended client with the new key right away. Confirm in Audit that new calls use the replacement.

Revocation stops future calls using that client credential. It does not revoke the user's other AI clients, provider credentials, or workspace membership.

Wrong workspace

If a client is connected to the wrong workspace:

Revoke or disconnect the client.
Select the intended workspace in Stackyapper.
Start authorization again, and read the consent screen before approving it.
Run a harmless read and verify its workspace in Audit.