For the complete documentation index, see [llms.txt](https://docs.archera.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.archera.ai/api-reference/public-api/oauth.md).

# OAuth

OAuth 2.0 authorization endpoints for third-party integrations

## Redirect to React consent page.

> Query Parameters (handled by Authlib):  
>   client_id: OAuth client identifier  
>   redirect_uri: Where to redirect after authorization  
>   response_type: Must be 'code'  
>   scope: Space-separated list of requested scopes  
>   state: CSRF protection token (optional but recommended)  
>   code_challenge: PKCE code challenge  
>   code_challenge_method: PKCE method (usually 'S256')  
>  
> Returns:  
>   Redirect to React consent page with OAuth params and client info

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"tags":[{"name":"OAuth","description":"OAuth 2.0 authorization endpoints for third-party integrations"}],"paths":{"/oauth/authorize":{"get":{"responses":{"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"summary":"Redirect to React consent page.","description":"Query Parameters (handled by Authlib):\n    client_id: OAuth client identifier\n    redirect_uri: Where to redirect after authorization\n    response_type: Must be 'code'\n    scope: Space-separated list of requested scopes\n    state: CSRF protection token (optional but recommended)\n    code_challenge: PKCE code challenge\n    code_challenge_method: PKCE method (usually 'S256')\n\nReturns:\n    Redirect to React consent page with OAuth params and client info","tags":["OAuth"]}}},"components":{"schemas":{"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Handle user authorization decision from React consent page.

> Query Parameters:  
>   All OAuth params from GET (client_id, redirect_uri, state, etc.)  
>  
> Form Parameters:  
>   confirm: 'yes' to authorize, 'no' to deny  
>  
> Returns:  
>   Redirect to client with authorization code or error

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"tags":[{"name":"OAuth","description":"OAuth 2.0 authorization endpoints for third-party integrations"}],"paths":{"/oauth/authorize":{"post":{"responses":{"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"summary":"Handle user authorization decision from React consent page.","description":"Query Parameters:\n    All OAuth params from GET (client_id, redirect_uri, state, etc.)\n\nForm Parameters:\n    confirm: 'yes' to authorize, 'no' to deny\n\nReturns:\n    Redirect to client with authorization code or error","tags":["OAuth"]}}},"components":{"schemas":{"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Issue access tokens.

> Form Parameters (authorization_code grant):  
>   grant_type: Must be 'authorization_code'  
>   code: Authorization code from /authorize  
>   redirect_uri: Must match original request  
>   client_id: OAuth client identifier  
>   code_verifier: PKCE code verifier  
>  
> Form Parameters (refresh_token grant):  
>   grant_type: Must be 'refresh_token'  
>   refresh_token: Valid refresh token  
>   client_id: OAuth client identifier  
>  
> Returns:  
>   JSON response with access_token (JWT), refresh_token, expires_in, etc.

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"tags":[{"name":"OAuth","description":"OAuth 2.0 authorization endpoints for third-party integrations"}],"paths":{"/oauth/token":{"post":{"responses":{"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"summary":"Issue access tokens.","description":"Form Parameters (authorization_code grant):\n    grant_type: Must be 'authorization_code'\n    code: Authorization code from /authorize\n    redirect_uri: Must match original request\n    client_id: OAuth client identifier\n    code_verifier: PKCE code verifier\n\nForm Parameters (refresh_token grant):\n    grant_type: Must be 'refresh_token'\n    refresh_token: Valid refresh token\n    client_id: OAuth client identifier\n\nReturns:\n    JSON response with access_token (JWT), refresh_token, expires_in, etc.","tags":["OAuth"]}}},"components":{"schemas":{"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## List all active OAuth sessions for the current user.

> Returns:  
> List of active sessions including client info, creation time, and scope

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"tags":[{"name":"OAuth","description":"OAuth 2.0 authorization endpoints for third-party integrations"}],"paths":{"/oauth/sessions":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/OAuthSessionResponse"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"summary":"List all active OAuth sessions for the current user.","description":"Returns:\nList of active sessions including client info, creation time, and scope","tags":["OAuth"]}}},"components":{"schemas":{"OAuthSessionResponse":{"type":"object","properties":{"token_id":{"type":"string","pattern":"[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\Z"},"client_name":{"type":"string"},"client_id":{"type":"string"},"created_at":{"type":"integer"},"scope":{"type":"string"}},"required":["client_id","client_name","created_at","scope","token_id"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Revoke a specific OAuth session by token ID.

> Args:  
>   token_id: UUID of the OAuth token to revoke  
>  
> Returns:  
>   204 No Content on success  
>   404 Not Found if session doesn't exist or doesn't belong to user

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"tags":[{"name":"OAuth","description":"OAuth 2.0 authorization endpoints for third-party integrations"}],"paths":{"/oauth/sessions/{token_id":{"delete":{"responses":{"204":{"description":"No Content"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"summary":"Revoke a specific OAuth session by token ID.","description":"Args:\n    token_id: UUID of the OAuth token to revoke\n\nReturns:\n    204 No Content on success\n    404 Not Found if session doesn't exist or doesn't belong to user","tags":["OAuth"]}}},"components":{"schemas":{"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Revoke all OAuth sessions (refresh tokens) for the current user across all clients.

> Returns:  
> JSON with message and count of revoked sessions

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"tags":[{"name":"OAuth","description":"OAuth 2.0 authorization endpoints for third-party integrations"}],"paths":{"/oauth/revoke-all":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokeAllSessionsResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"summary":"Revoke all OAuth sessions (refresh tokens) for the current user across all clients.","description":"Returns:\nJSON with message and count of revoked sessions","tags":["OAuth"]}}},"components":{"schemas":{"RevokeAllSessionsResponse":{"type":"object","properties":{"message":{"type":"string"},"count":{"type":"integer"}},"required":["count","message"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Revoke an access token or refresh token.

> Form Parameters:  
>   token: The token to revoke (access_token or refresh_token)  
>   token_type_hint: Optional hint about token type ('access_token' or 'refresh_token')  
>  
> Returns:  
>   200 response (always returns 200 per RFC 7009, even for invalid tokens)

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"tags":[{"name":"OAuth","description":"OAuth 2.0 authorization endpoints for third-party integrations"}],"paths":{"/oauth/revoke":{"post":{"responses":{"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"summary":"Revoke an access token or refresh token.","description":"Form Parameters:\n    token: The token to revoke (access_token or refresh_token)\n    token_type_hint: Optional hint about token type ('access_token' or 'refresh_token')\n\nReturns:\n    200 response (always returns 200 per RFC 7009, even for invalid tokens)","tags":["OAuth"]}}},"components":{"schemas":{"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## POST /oauth/register

>

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"tags":[{"name":"OAuth","description":"OAuth 2.0 authorization endpoints for third-party integrations"}],"paths":{"/oauth/register":{"post":{"responses":{"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["OAuth"]}}},"components":{"schemas":{"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```