# Altss Console agent authorization

The public website reader at https://altss.com/mcp remains anonymous. This guide
applies only to the protected paid Console at https://console.altss.com/v1/console.
Scope company.read permits the organization's available Console tool catalog,
quoted financial-research execution and its own results/receipts, subject to the
approved API/MCP channel and spending limits. It does not grant unrestricted data access.
Terms: https://altss.com/terms-of-use; privacy: https://altss.com/privacy-policy;
pricing: https://console.altss.com/pricing; integration support: https://altss.com/contact.

## OAuth authorization code with CIMD
Public OAuth clients may use authorization_code with S256 and a public HTTPS client metadata document as client_id. Discover authorization_endpoint in the authorization-server metadata. Request response_type=code, client_id, an exactly registered redirect_uri, scope=company.read, resource=https://console.altss.com/v1/console/mcp, code_challenge and code_challenge_method=S256; retain unpredictable state. The signed-in authorized human reviews the exact client, workspace, resource and explicit limits using fresh reauthentication. Denial and success include iss=https://console.altss.com; validate both iss and state. Numeric HTTP loopback callbacks may vary only their port. Metadata is fetched without redirects or ambient credentials and is not a client endorsement.

Redeem the single-use code within two minutes at the token endpoint using application/x-www-form-urlencoded grant_type=authorization_code, code, the same client_id, exact redirect_uri and resource, and the original code_verifier. No Basic authentication, client_secret, external assertions or refresh tokens are accepted for this public-client flow. The returned Bearer credential is restricted to MCP, carries company.read and the human-approved ceilings, and expires after at most 3600 seconds. The token endpoint returns actual expires_in. This credential cannot be rotated through manual or legacy claim flows; obtain new consent instead. Its client/resource/limits/expiry binding is durable and enforced on every use. Revocation uses token, client_id and optional token_type_hint=access_token at the existing revocation endpoint; the owning client may also revoke an expired token. Humans can revoke it through Console Credentials. New issuance can be disabled without bypassing existing token expiry/revocation. No dynamic client registration or confidential-client authentication is advertised.

## Pick a method
For the protected Console, use the service_auth user-claimed method below, or an
existing manually created scoped Console key. The separate public website MCP reader
is anonymous and cannot access paid Console resources. Provider identity_assertion
registration using ID-JAG is not supported: no provider trust or events endpoint is
configured. This implementation follows the user-claimed service flow in
https://workos.com/auth-md/docs/apps with the explicit limits and S256 proof below.

## Discover
For MCP, read https://console.altss.com/.well-known/oauth-protected-resource/v1/console/mcp;
its resource is the exact MCP endpoint https://console.altss.com/v1/console/mcp. The canonical MCP
endpoint's 401 response includes this resource_metadata hint. For the existing API
resource, read https://console.altss.com/.well-known/oauth-protected-resource/v1/console. Other
protected REST routes return a plain Bearer challenge. Both resources use
https://console.altss.com/.well-known/oauth-authorization-server. The existing manually created
Console API keys remain supported. Never send an Auth0 account token to machine APIs.

## Register
Only service_auth is enabled. External identity assertions, anonymous registration,
provider events and refresh_token grants are not supported. Generate a private random
43–128-character PKCE code_verifier and its base64url SHA-256 code_challenge (S256).
POST JSON to https://console.altss.com/v1/console/agent-auth/identity:

```json
{"type":"service_auth","login_hint":"you@example.com","name":"My research agent","scope":"company.read","channels":["API","MCP"],"max_request_amount_minor":2500,"daily_spend_limit_minor":10000,"rate_limit_per_minute":30,"code_challenge":"<S256 challenge>","code_challenge_method":"S256"}
```

Amounts are USD cents and are proposed spending limits, not a payment or free credit.
Retain top-level claim_token and the original code_verifier privately. Show the user
claim.user_code and claim.verification_uri from the nested claim object; its
claim.interval is the polling interval. Never put claim_token in a URL.
Registration reveals no account existence.
These explicit limits and S256 proof are required by this service's profile.
To replace an unexpired pending claim ceremony, POST JSON to claim_url with
claim_token, email equal to login_hint, and the original code_verifier. At most two
replacements are allowed; they do not extend the original ten-minute expiration.
The replacement response uses claim_attempt.user_code and claim_attempt.verification_uri;
discard the previous attempt URL and code. Keep the same private claim_token/verifier.

## Claim and approve
The human signs in using the existing Console login, accepts current terms, and
re-authenticates before approving the displayed agent, channels and exact limits.
Their verified email must match login_hint and their current organization must grant
billing authority. They enter user_code on the Console claim form. Approval does not
fund a wallet or authorize a particular paid execution. Claims expire after ten minutes;
approved grants must be redeemed within two minutes. Five incorrect code attempts lock a claim.
If the claim page asks to verify an email, the human must first open their Console
verification email and complete its verification link, then explicitly sign in again.
Where enabled, the human can use Send verification email on that page. It sends only
to their signed-in provider account, at most once per minute and three times per hour.
An accepted request is not proof of delivery or verification; no agent can perform
the email-verification or approval ceremony for the human.
Signing in alone does not verify an email. If verification takes beyond the claim's
ten-minute lifetime, start a new registration; the original expiration is not extended.

## Exchange
Poll the token_endpoint no faster than once every five seconds with a form-encoded
POST containing grant_type=urn:workos:agent-auth:grant-type:claim, claim_token,
code_verifier, and resource=https://console.altss.com/v1/console for the existing API grant.
For an MCP-specific grant, use resource=https://console.altss.com/v1/console/mcp. The human must
have approved the MCP channel; the issued key is restricted to MCP, even if API
was also approved. The API resource preserves the approved channel set. The chosen
resource is bound to the grant and its signed assertion and cannot change during rotation.
authorization_pending means wait for approval; slow_down means wait longer. expired_token
or invalid_grant requires a new registration and human approval. Never automatically approve.
Success returns access_token, token_type=Bearer, scope=company.read, and a short-lived
service-signed identity_assertion with assertion_expires. The access token is a
revocable Console API key without scheduled expiry, so expires_in is omitted.

During the two-minute approval window, the assertion may be exchanged ONCE using
grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer, assertion, the original
code_verifier and the same resource. It rotates the SAME principal's key, invalidates
the previous key immediately and preserves its effective scope, channels and spending limits.
The assertion's audience is this authorization server; its separate resource claim
binds the target. Existing base-resource assertions without that claim remain base-only.
It returns no new assertion or refresh token. Expired, consumed or revoked grants
cannot renew. Every exchange rechecks current human authority and fresh reauthentication.
A lost token response cannot replay issuance; restart registration if no usable assertion remains.

## Errors
| Error | Action |
| --- | --- |
| authorization_pending | Wait for the human to finish; poll at most once every five seconds. |
| slow_down | Wait longer than five seconds before another poll. |
| rate_limit_exceeded | Stop rapid retries; wait for the rate window or contact support. |
| invalid_request | Check the exact JSON/form schema, company.read scope, channels, positive limits and S256 proof format; do not add broader scopes. |
| unsupported_grant_type | Use only an advertised grant supported by the selected authentication method; refresh_token is unsupported. |
| invalid_target | Use exactly https://console.altss.com/v1/console or https://console.altss.com/v1/console/mcp; MCP requires the approved MCP channel. Keep the original resource for assertion exchange. |
| invalid_grant | Stop replaying: the proof may be wrong, the attempt replaced/locked, or the grant/assertion consumed or revoked. Start a fresh human-approved registration if needed. |
| expired_token | The claim or approval expired; start again with explicit human approval. |
| login_required / reauthentication_required | The human must use the provided secure sign-in page; the agent cannot supply their password or approve for them. |
| email_verification_required | The human must verify the same account's email using its verification email, then sign in again to refresh the session. Contact support if a verification email is unavailable. Start a new registration if the claim has expired. |
| access_denied | Check the human's verified email, selected organization, current terms, Console admission and billing permission. Do not bypass a denial. |
| temporarily_unavailable | Retry discovery later. If a token response was lost or issuance began, check/revoke the prior credential in Console before starting a replacement; issuance is not replayable. |

No error response contains account-existence details, tokens or provider errors.

## Use the access token
Send Authorization: Bearer <access_token> only to https://console.altss.com. Start with
GET /v1/console/tools or POST /v1/console/mcp initialize and tools/list. API and MCP
channels must have been approved. Obtain a current quote and the purchaser's explicit
execution authority before any paid run. Existing wallet, privacy, license, tenant and
output restrictions apply. See https://console.altss.com/connect and https://console.altss.com/pricing.

## Revocation
POST application/x-www-form-urlencoded token=<access_token>&token_type_hint=access_token
to https://console.altss.com/v1/console/agent-auth/revoke. Revocation is terminal for this agent principal,
including its remaining assertion; unknown/already revoked tokens return 200 without details.
Humans can also revoke it in https://console.altss.com/console/credentials. A new key requires fresh
human approval. No provider events endpoint is advertised because no external provider
trust has been configured. Stop using a revoked key; never bypass a restriction.
