Skip to main content
BETA
MenuClose

OAuth

2 operations in the Tolvi API, version 1. Paths are relative to https://api.tolvi.co.uk. Every amount is integer pence.

OAuth protected-resource metadata

GET/.well-known/oauth-protected-resource

Access
No authentication.

Where OAuth 2.1 and MCP clients find the authorization server.

Responses

200 OK, application/json

Body: object (ProtectedResourceMetadata).

RFC 9728 protected-resource metadata.

200 OK response for GET /.well-known/oauth-protected-resource
FieldTypeDescription
resourcerequiredstring (uri)
authorization_serversrequiredarray of string
scopes_supportedrequiredarray of string
bearer_methods_supportedrequiredarray of string
resource_namerequiredstring

Errors: 429 Too many requests, as problem details (application/problem+json).

Get an access token (client credentials)

POST/api/v1/oauth/token

Access
No authentication.

Authenticate with HTTP Basic (client_id:client_secret) or client_id and client_secret in the body. The token acts as the API client: its scopes, capped by the client’s role.

Request body

Required. application/x-www-form-urlencoded or application/json: object (ClientCredentialsTokenRequest).

Request body for POST /api/v1/oauth/token
FieldTypeDescription
grant_typerequiredstring (GrantType)

One of: client_credentials

client_idstring

Or send HTTP Basic authentication.

client_secretstring
scopestring

Space-separated subset of the client’s scopes (default: all of them).

Responses

200 OK, application/json

Body: object (TokenResponse).

200 OK response for POST /api/v1/oauth/token
FieldTypeDescription
access_tokenrequiredstring

example "twat_…"

token_typerequiredstring (TokenType)

One of: Bearer

expires_inrequiredinteger

example 3600

scoperequiredstring

example "work:read clients:read"

400 Bad request, application/json

invalid_request, unsupported_grant_type or invalid_scope.

Body: object (OAuthError).

RFC 6749 §5.2 error response.

400 Bad request response for POST /api/v1/oauth/token
FieldTypeDescription
errorrequiredstring (OAuthErrorCode)

One of: invalid_request, invalid_client, invalid_grant, unauthorized_client, unsupported_grant_type, invalid_scope

error_descriptionstring

401 Unauthorised, application/json

invalid_client.

Body: object (OAuthError).

RFC 6749 §5.2 error response.

401 Unauthorised response for POST /api/v1/oauth/token
FieldTypeDescription
errorrequiredstring (OAuthErrorCode)

One of: invalid_request, invalid_client, invalid_grant, unauthorized_client, unsupported_grant_type, invalid_scope

error_descriptionstring

Errors: 429 Too many requests, as problem details (application/problem+json).