# Auth.md

Novita AI supports agent-facing authentication and registration through OAuth discovery metadata and user-approved OAuth authorization.

## Service

- Name: Novita AI
- Website: https://novita.ai
- Documentation: https://docs.novita.ai/guides/introduction
- OAuth authorization server metadata: https://novita.ai/.well-known/oauth-authorization-server
- OAuth protected resource metadata: https://novita.ai/.well-known/oauth-protected-resource

## Agent Registration

Agents should register or request access by using the OAuth authorization code flow with PKCE.

1. Fetch https://novita.ai/.well-known/oauth-protected-resource to discover the protected resource and authorization server.
2. Fetch https://novita.ai/.well-known/oauth-authorization-server and read the agent_auth block.
3. Send the user to the register_uri with a client_id, redirect_uri, response_type=code, requested scope, state, and S256 PKCE challenge.
4. Exchange the returned authorization code at https://api-server.novita.ai/oauth/token.
5. Use the issued access token as a Bearer token for Novita APIs that accept OAuth credentials.

## Supported Identity Types

- user_claimed: the user signs in to Novita AI and approves the agent or OAuth client.

## Supported Credential Types

- oauth_access_token: issued by the OAuth token endpoint after user approval.
- api_key: available from the Novita console for APIs that require API key authentication.

## Scopes

- openid
- profile
- email
- api
- balance:read

## Claim and Revocation

- Claim URI: https://novita.ai/oauth/authorize
- Credential management URI: https://novita.ai/settings/key-management
- Revocation: users can revoke or delete API keys from the credential management URI. OAuth token revocation is not advertised as a machine endpoint until a public revocation endpoint is available.

## Security Notes

- Agents must request only the minimum scopes needed for the task.
- Agents must keep access tokens and API keys secret.
- Agents must send API keys with Authorization: Bearer <NOVITA_API_KEY> where API key authentication is required.
- Agents must send OAuth access tokens with Authorization: Bearer <ACCESS_TOKEN> where OAuth authentication is supported.