Authentication
Delegated OAuth to start self-serve, service credentials for unattended backends.
Two modes
| Mode | Who | Grant | Issuer | Setup |
|---|---|---|---|---|
| Delegated | Agents and backends acting for a signed-in user; people in ChatGPT, Claude or another MCP client | OAuth 2.1 authorization code + PKCE, with refresh tokens | https://auth.aginera.ai | Self-serve — register a public client and start today |
| Service | Fully unattended partner backends, CI, batch jobs | OAuth 2.0 client credentials | Microsoft Entra ID (Aginera tenant) | Provisioned during partner onboarding |
Both produce a bearer token for Authorization: Bearer … against https://api.aginera.ai/partner/v1, and both hit the same services, permissions and billing. Tokens are never accepted from browser sessions.
Which to use. Start with delegated — it needs no partner setup: register a public client, have a user approve once, and refresh tokens keep the connection alive. Move to service credentials when you need a fully unattended backend with no human in the loop; email developers@aginera.ai to be provisioned. See the REST quickstart for both flows end to end.
Delegated: register a client
No client secret is issued. Register a public client (token_endpoint_auth_method: "none") at the registration endpoint, or advertise a Client ID Metadata Document — both are supported (client_id_metadata_document_supported: true). Then run authorization code + PKCE (code_challenge_method=S256) and exchange the code for an access token plus a rotating refresh token.
Scopes
projects:read/write/delete, documents:read/write/delete, takeoffs:read/run/review/delete, exports:read/create, estimates:read/generate, billing:read/write, events:read, webhooks:manage. A token only ever carries the scopes it was granted; request the narrowest set you need. Billable scopes (takeoffs:run, estimates:generate) and destructive scopes (*:delete) are highlighted on the consent screen.
Discovery
- Authorization server metadata:
https://auth.aginera.ai/.well-known/oauth-authorization-server(listsauthorization_endpoint,token_endpoint,registration_endpointandscopes_supported) - Protected resource metadata:
https://mcp.aginera.ai/.well-known/oauth-protected-resource(agents) andhttps://auth.aginera.ai/.well-known/oauth-protected-resource(REST →https://api.aginera.ai/partner/v1) - Public signing keys:
https://auth.aginera.ai/.well-known/jwks.json
Delegated access tokens are RS256, iss=https://auth.aginera.ai, aud=https://mcp.aginera.ai, and expire in one hour; refresh before expiry with grant_type=refresh_token.