Lifecycle & API keys

The AI clients page in the portal contains connection URLs for interactive OAuth clients and your direct API key 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 a direct API key only when the software cannot complete the supported OAuth flow. Open AI clients → Connect and, under Your direct API key, select New API key. If you already have a key, the button reads Rotate API key.

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

The key list shows Never used or when the key was last used. Treat an unexpectedly unused or active key as a reason to verify where it is configured.

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 Revoke 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 access 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 an API key, select Revoke, or rotate it with Rotate API key → Revoke and rotate: creating the replacement revokes your previous key immediately, so update the intended client with the new key right away. Confirm in Audit that new calls use the replacement.

For an OAuth client, remove the Stackyapper connection in the AI client. An owner or admin can also block a client registration under AI clients → Access rules.

Control workspace client access

Workspace owners and admins can manage access under AI clients → Access rules. Choose a workspace policy first; a workspace without a configured policy retains its existing compatibility behavior.

Product rules → Block for everyone denies registrations recognized as that product for every member in the workspace. Member and group exceptions and exact registration allows cannot override it. Existing OAuth tokens are denied on their next request. Removing this block restores the previous defaults and exceptions and may require signing in again.
A Product default can be overridden by member, group, or exact registration allows. Keep this separate from a block for everyone.
Client registrations shows the exact registration, its identity evidence, reported software name and version, and recent usage. Open a registration and choose a member under Check a member’s effective access to see how the current rules apply to that person.

A registration may be shared by several people; each person authorizes their own connection. An access check shows permission, not proof of an existing connection. Software names and versions are client-reported. Directory matches help identify familiar names but do not verify the software or grant access. The underlying agent or model may remain unknown.

Product blocks apply only where Stackyapper has recognized OAuth product evidence. Direct API keys do not establish which software holds them; manage them with the workspace’s direct-key policy and member or group rules.

Revoking an API key stops future calls using that key. 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:

Remove the Stackyapper connection from the client, or revoke its API key.
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.