OAuth API¶

The OAuth API is the OAuth 2.0 surface for token issuance, refresh, and introspection. The authorization endpoint lives on the auth service; the token and refresh endpoints live here on public-api.

For the conceptual overview of how OAuth fits into Skynet — grant types, scopes, client registration, personal token semantics — see Auth. This page covers the endpoints themselves.

Endpoints at a glance¶

Endpoint	Purpose
`POST /oauth/token`	Exchange an authorization code for access + refresh tokens (auth code grant only)
`POST /oauth/token/refresh`	Exchange a refresh token for a new access (and refresh) token
`POST /oauth/token/introspect`	Inspect a token's validity and metadata (admin / first-party clients only)
`POST /oauth/token/revoke`	Revoke an active token

The authorization endpoint (/oauth/authorize) is served by apps/auth/, not by this router.

Supported flows¶

Authorization code with PKCE. The only grant type supported for new code exchange. The authorization endpoint accepts a code_challenge; the token endpoint verifies it.
Refresh token rotation. Calling /oauth/token/refresh returns a new refresh token; the old one is invalidated. Always replace the stored refresh token with the new one.

There is no client_credentials, password, or implicit grant. See Auth — Grant types.

Client identifiers¶

Every token-endpoint call carries client_id and (for confidential clients) client_secret. Confidential clients send the secret in the request body; public clients omit it and rely on PKCE for authorization-code verification.

Common pitfalls¶

Missing PKCE on the authorize step. The token endpoint will reject the code exchange if the authorize step didn't include a code challenge.
Reusing an authorization code. Codes are single-use; trying to reuse one returns an error.
Refresh token rotation. When refresh returns a new refresh token, replace the stored copy immediately or you'll be locked out at the next refresh.

Reference¶

OAuth API 2.0.0¶

Endpoints for managing OAuth authentication and authorization.

OAuth¶

GET /oauth/clients¶

Get Oauth Clients

Description

Return all registered OAuth clients.

Responses

200 OK

application/json

[
    {
        "allowedScopes": null,
        "clientId": "string",
        "createdAt": null,
        "description": null,
        "logoUrl": null,
        "name": "string",
        "redirectUris": [
            "string"
        ]
    }
]

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "items": {
        "$ref": "#/components/schemas/OAuthClient"
    },
    "title": "Response Get Oauth Clients Oauth Clients Get",
    "type": "array"
}

GET /oauth/clients/{client_id}¶

Get Oauth Client

Description

Return a specific registered OAuth client.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`client_id`	path	string		No

Responses

200 OK422 Unprocessable Entity

application/json

{
    "allowedScopes": null,
    "clientId": "string",
    "createdAt": null,
    "description": null,
    "logoUrl": null,
    "name": "string",
    "redirectUris": [
        "string"
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "allowedScopes": {
            "anyOf": [
                {
                    "items": {
                        "type": "string"
                    },
                    "type": "array"
                },
                {
                    "type": "null"
                }
            ],
            "description": "Allowed scopes"
        },
        "clientId": {
            "description": "Unique client identifier",
            "type": "string"
        },
        "createdAt": {
            "anyOf": [
                {
                    "format": "date-time",
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "description": "Creation timestamp"
        },
        "description": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "description": "Description of the client"
        },
        "logoUrl": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "description": "Logo URL"
        },
        "name": {
            "description": "Name of the client",
            "type": "string"
        },
        "redirectUris": {
            "description": "Allowed redirect URIs",
            "items": {
                "type": "string"
            },
            "type": "array"
        }
    },
    "required": [
        "clientId",
        "redirectUris",
        "name"
    ],
    "title": "OAuthClient",
    "type": "object"
}

application/json

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "title": "Detail",
            "type": "array"
        }
    },
    "title": "HTTPValidationError",
    "type": "object"
}

POST /oauth/revoke¶

Revoke Token Post

Description

RFC 7009-style token revocation.

Revokes the presented bearer token and the caller's entire grant for the same client (access + refresh), so an API client — e.g. the Afterglow data provider disconnecting — can sever its own access. Always returns 200, per RFC 7009. (User-initiated revocation of a client lives at DELETE /v1/me/connected-apps/{client_id}.)

Input parameters

Parameter	In	Type	Default	Nullable	Description
`token`	query			No

Responses

200 OK422 Unprocessable Entity

application/json

Schema of the response body

application/json

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "title": "Detail",
            "type": "array"
        }
    },
    "title": "HTTPValidationError",
    "type": "object"
}

POST /oauth/sign-out¶

Sign Out Post

Input parameters

Parameter	In	Type	Default	Nullable	Description
`token`	query			No

Responses

204 No Content422 Unprocessable Entity

application/json

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "title": "Detail",
            "type": "array"
        }
    },
    "title": "HTTPValidationError",
    "type": "object"
}

Schemas¶

HTTPValidationError¶

Name	Type	Description
`detail`	Array<ValidationError>

OAuthClient¶

Name	Type	Description
`allowedScopes`		Allowed scopes
`clientId`	string	Unique client identifier
`createdAt`		Creation timestamp
`description`		Description of the client
`logoUrl`		Logo URL
`name`	string	Name of the client
`redirectUris`	Array<string>	Allowed redirect URIs

ValidationError¶

Name	Type	Description
`ctx`
`input`
`loc`	Array<>
`msg`	string
`type`	string