API docs by Redocly

authbase (0.0.0)

Download OpenAPI specification:

License: Apache-2.0

Self-hosted authentication service. This document is the contract: the Go server, the dashboard client and the SDK are generated from it, and every request is validated against it before reaching a handler.

Errors are RFC 9457 problem documents (application/problem+json) with a stable machine-readable code.

operational

Health and readiness probes.

Liveness probe

Returns 200 as soon as the process is up. Does not touch the database.

Responses

Response samples

Content type
application/json
{
  • "status": "ok"
}

Readiness probe

Returns 200 when the database answers and every embedded migration has been applied; 503 with code not_ready otherwise.

Responses

Response samples

Content type
application/json
{
  • "status": "ok",
  • "checks": {
    }
}

accounts

Sign up for a platform account

Request Body schema: application/json
required
email
required
string <email> <= 254 characters
password
required
string <password> (Password) [ 12 .. 128 ] characters

12–128 characters, no composition rules (ARCHITECTURE §3.8, ASVS 4.0.3 2.1.1).

name
string <= 100 characters

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "password": "pa$$word_qwe",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "user@example.com",
  • "email_verified": true,
  • "name": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Email a platform account a password-reset link

Always 202, whether or not the address has an account. The link opens {PUBLIC_URL}/account/reset-password, is single-use and expires in 30 minutes.

Request Body schema: application/json
required
email
required
string <email> <= 254 characters

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com"
}

Response samples

Content type
application/problem+json
{
  • "type": "http://example.com",
  • "title": "string",
  • "status": 100,
  • "detail": "string",
  • "instance": "string",
  • "code": "malformed_request",
  • "errors": [
    ],
  • "request_id": "string"
}

Set a new account password with a reset token

Consumes the token, sets the password, verifies the email address and ends every dashboard session of the account.

Request Body schema: application/json
required
token
required
string (OneTimeToken) [ 1 .. 128 ] characters

The token query parameter of the emailed link.

new_password
required
string <password> (Password) [ 12 .. 128 ] characters

12–128 characters, no composition rules (ARCHITECTURE §3.8, ASVS 4.0.3 2.1.1).

Responses

Request samples

Content type
application/json
{
  • "token": "string",
  • "new_password": "pa$$word_qwe"
}

Response samples

Content type
application/problem+json
{
  • "type": "http://example.com",
  • "title": "string",
  • "status": 100,
  • "detail": "string",
  • "instance": "string",
  • "code": "malformed_request",
  • "errors": [
    ],
  • "request_id": "string"
}

Email a platform account a verification link

Public, so an account blocked by AUTHBASE_REQUIRE_ACCOUNT_EMAIL_VERIFICATION can ask again. Always 202; verified, disabled or unknown addresses get no email. The link opens {PUBLIC_URL}/account/verify-email and expires in 24 hours.

Request Body schema: application/json
required
email
required
string <email> <= 254 characters

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com"
}

Response samples

Content type
application/problem+json
{
  • "type": "http://example.com",
  • "title": "string",
  • "status": 100,
  • "detail": "string",
  • "instance": "string",
  • "code": "malformed_request",
  • "errors": [
    ],
  • "request_id": "string"
}

Mark an account's address verified with a verification token

Request Body schema: application/json
required
token
required
string (OneTimeToken) [ 1 .. 128 ] characters

The token query parameter of the emailed link.

Responses

Request samples

Content type
application/json
{
  • "token": "string"
}

Response samples

Content type
application/problem+json
{
  • "type": "http://example.com",
  • "title": "string",
  • "status": 100,
  • "detail": "string",
  • "instance": "string",
  • "code": "malformed_request",
  • "errors": [
    ],
  • "request_id": "string"
}

Log in (sets the session cookie)

Request Body schema: application/json
required
email
required
string <email> <= 254 characters
password
required
string <password> <= 128 characters

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "password": "pa$$word"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "user@example.com",
  • "email_verified": true,
  • "name": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Log out (deletes the session)

Authorizations:
sessionCookie

Responses

Response samples

Content type
application/problem+json
{
  • "type": "http://example.com",
  • "title": "string",
  • "status": 100,
  • "detail": "string",
  • "instance": "string",
  • "code": "malformed_request",
  • "errors": [
    ],
  • "request_id": "string"
}

Current account

Authorizations:
sessionCookie

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "user@example.com",
  • "email_verified": true,
  • "name": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update name or email

Changing the email requires current_password (ASVS 3.7.1) and clears email_verified. A wrong current password answers invalid_credentials.

Authorizations:
sessionCookie
Request Body schema: application/json
required
non-empty
name
string <= 100 characters
email
string <email> <= 254 characters
current_password
string <password> <= 128 characters

Required when email is set; verified whenever present.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "email": "user@example.com",
  • "current_password": "pa$$word"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "user@example.com",
  • "email_verified": true,
  • "name": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete the account

Requires current_password (ASVS 3.7.1). Refused with account_owns_apps while the account owns apps (ADR-018).

Authorizations:
sessionCookie
Request Body schema: application/json
required
current_password
required
string <password> <= 128 characters

Responses

Request samples

Content type
application/json
{
  • "current_password": "pa$$word"
}

Response samples

Content type
application/problem+json
{
  • "type": "http://example.com",
  • "title": "string",
  • "status": 100,
  • "detail": "string",
  • "instance": "string",
  • "code": "malformed_request",
  • "errors": [
    ],
  • "request_id": "string"
}

List the account's live dashboard sessions

Newest first; current marks the session making this request.

Authorizations:
sessionCookie

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Sign one dashboard session out

Another account's session, or an unknown id, is 404. Revoking the current session also clears the cookie.

Authorizations:
sessionCookie
path Parameters
sessionId
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "type": "http://example.com",
  • "title": "string",
  • "status": 100,
  • "detail": "string",
  • "instance": "string",
  • "code": "malformed_request",
  • "errors": [
    ],
  • "request_id": "string"
}

Change password

Requires the current password. Every other session of the account is revoked.

Authorizations:
sessionCookie
Request Body schema: application/json
required
current_password
required
string <password> <= 128 characters
new_password
required
string <password> (Password) [ 12 .. 128 ] characters

12–128 characters, no composition rules (ARCHITECTURE §3.8, ASVS 4.0.3 2.1.1).

Responses

Request samples

Content type
application/json
{
  • "current_password": "pa$$word",
  • "new_password": "pa$$word_qwe"
}

Response samples

Content type
application/problem+json
{
  • "type": "http://example.com",
  • "title": "string",
  • "status": 100,
  • "detail": "string",
  • "instance": "string",
  • "code": "malformed_request",
  • "errors": [
    ],
  • "request_id": "string"
}

apps

Create an app

Generates the app's first Ed25519 signing key. The slug is immutable (ADR-028).

Authorizations:
sessionCookie
Request Body schema: application/json
required
name
required
string [ 1 .. 100 ] characters
slug
required
string [ 1 .. 63 ] characters ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$

Lowercase letters, digits and hyphens. Immutable; appears in the issuer URL.

object (AppSettings)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "slug": "string",
  • "settings": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "slug": "string",
  • "name": "string",
  • "settings": {
    },
  • "issuer": "string",
  • "jwks_uri": "string",
  • "discovery_uri": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List the account's apps

Authorizations:
sessionCookie

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get an app

Authorizations:
sessionCookie
path Parameters
appId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "slug": "string",
  • "name": "string",
  • "settings": {
    },
  • "issuer": "string",
  • "jwks_uri": "string",
  • "discovery_uri": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update name or settings

Settings keys not present are left unchanged. The slug cannot change.

Authorizations:
sessionCookie
path Parameters
appId
required
string <uuid>
Request Body schema: application/json
required
non-empty
name
string [ 1 .. 100 ] characters
object (AppSettings)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "settings": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "slug": "string",
  • "name": "string",
  • "settings": {
    },
  • "issuer": "string",
  • "jwks_uri": "string",
  • "discovery_uri": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete an app and everything under it

Final. confirm must equal the app's slug. Cascades to users, keys, tokens and the app's audit events (ADR-018).

Authorizations:
sessionCookie
path Parameters
appId
required
string <uuid>
Request Body schema: application/json
required
confirm
required
string

Must equal the app's slug.

Responses

Request samples

Content type
application/json
{
  • "confirm": "string"
}

Response samples

Content type
application/problem+json
{
  • "type": "http://example.com",
  • "title": "string",
  • "status": 100,
  • "detail": "string",
  • "instance": "string",
  • "code": "malformed_request",
  • "errors": [
    ],
  • "request_id": "string"
}

api-keys

List API keys

Authorizations:
sessionCookie
path Parameters
appId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create an API key

The plaintext key is returned once, in this response only.

Authorizations:
sessionCookie
path Parameters
appId
required
string <uuid>
Request Body schema: application/json
required
name
required
string [ 1 .. 100 ] characters

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "prefix": "string",
  • "status": "active",
  • "created_at": "2019-08-24T14:15:22Z",
  • "last_used_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "revoked_at": "2019-08-24T14:15:22Z",
  • "key": "string"
}

Rotate API keys

Creates a new key and gives every other live key an expiry of now + grace (default: the app's api_key_rotation_grace_s, 0 allowed). Both keys work during the grace period.

Authorizations:
sessionCookie
path Parameters
appId
required
string <uuid>
Request Body schema: application/json
required
name
required
string [ 1 .. 100 ] characters
grace_seconds
integer [ 0 .. 604800 ]

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "grace_seconds": 0
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "prefix": "string",
  • "status": "active",
  • "created_at": "2019-08-24T14:15:22Z",
  • "last_used_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "revoked_at": "2019-08-24T14:15:22Z",
  • "key": "string"
}

Revoke an API key immediately

Authorizations:
sessionCookie
path Parameters
appId
required
string <uuid>
keyId
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "type": "http://example.com",
  • "title": "string",
  • "status": 100,
  • "detail": "string",
  • "instance": "string",
  • "code": "malformed_request",
  • "errors": [
    ],
  • "request_id": "string"
}

signing-keys

List signing keys

Authorizations:
sessionCookie
path Parameters
appId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Rotate the signing key

Generates a new active key. The previous key stays published as retiring until every token it could have signed has expired (max access-token TTL + 5 min), then is retired automatically.

Authorizations:
sessionCookie
path Parameters
appId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "alg": "string",
  • "status": "active",
  • "created_at": "2019-08-24T14:15:22Z",
  • "retire_after": "2019-08-24T14:15:22Z",
  • "retired_at": "2019-08-24T14:15:22Z",
  • "public_key": {
    }
}

JSON Web Key Set

Active and retiring public keys. Served with Cache-Control: public, max-age=300.

path Parameters
slug
required
string^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$

Responses

Response samples

Content type
application/json
{
  • "keys": [
    ]
}

OpenID discovery document

path Parameters
slug
required
string^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$

Responses

Response samples

Content type
application/json
{
  • "issuer": "string",
  • "jwks_uri": "string",
  • "id_token_signing_alg_values_supported": [
    ],
  • "subject_types_supported": [
    ]
}

end-user

The app behind the API key (whoami)

Authorizations:
apiKey

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "slug": "string",
  • "name": "string",
  • "settings": {
    },
  • "issuer": "string",
  • "jwks_uri": "string",
  • "discovery_uri": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

users

Register an end-user

Authorizations:
apiKey
Request Body schema: application/json
required
email
required
string <email> <= 254 characters
password
string <password> (Password) [ 12 .. 128 ] characters

12–128 characters, no composition rules (ARCHITECTURE §3.8, ASVS 4.0.3 2.1.1).

username
string (Username) [ 3 .. 64 ] characters ^[A-Za-z0-9._-]+$
object (Metadata)

Free-form JSON object, at most 16 KiB. Not included in access tokens.

roles
Array of strings (Roles) <= 50 items unique [ items [ 1 .. 64 ] characters ^[A-Za-z0-9_:.-]+$ ]

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "password": "pa$$word_qwe",
  • "username": "string",
  • "metadata": { },
  • "roles": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "user@example.com",
  • "username": "string",
  • "email_verified": true,
  • "roles": [
    ],
  • "metadata": { },
  • "disabled": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "last_login_at": "2019-08-24T14:15:22Z"
}

List users

Authorizations:
apiKey
query Parameters
q
string <= 254 characters

Case-insensitive prefix match on email or username.

role
string <= 64 characters

Only users holding this role.

limit
integer [ 1 .. 200 ]
Default: 50
cursor
string <= 512 characters

next_cursor from the previous page.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "next_cursor": "string"
}

Get a user

Authorizations:
apiKey
path Parameters
userId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "user@example.com",
  • "username": "string",
  • "email_verified": true,
  • "roles": [
    ],
  • "metadata": { },
  • "disabled": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "last_login_at": "2019-08-24T14:15:22Z"
}

Update a user

metadata replaces the whole object. username: null clears it.

Authorizations:
apiKey
path Parameters
userId
required
string <uuid>
Request Body schema: application/json
required
non-empty
email
string <email> <= 254 characters
username
string or null [ 3 .. 64 ] characters ^[A-Za-z0-9._-]+$
object (Metadata)

Free-form JSON object, at most 16 KiB. Not included in access tokens.

roles
Array of strings (Roles) <= 50 items unique [ items [ 1 .. 64 ] characters ^[A-Za-z0-9_:.-]+$ ]
disabled
boolean

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "username": "string",
  • "metadata": { },
  • "roles": [
    ],
  • "disabled": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "user@example.com",
  • "username": "string",
  • "email_verified": true,
  • "roles": [
    ],
  • "metadata": { },
  • "disabled": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "last_login_at": "2019-08-24T14:15:22Z"
}

Delete a user (final)

Authorizations:
apiKey
path Parameters
userId
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "type": "http://example.com",
  • "title": "string",
  • "status": 100,
  • "detail": "string",
  • "instance": "string",
  • "code": "malformed_request",
  • "errors": [
    ],
  • "request_id": "string"
}

Set a user's password (admin)

No current password needed. Every refresh-token family of the user is revoked. Audited as user.password_admin_set.

Authorizations:
apiKey
path Parameters
userId
required
string <uuid>
Request Body schema: application/json
required
password
required
string <password> (Password) [ 12 .. 128 ] characters

12–128 characters, no composition rules (ARCHITECTURE §3.8, ASVS 4.0.3 2.1.1).

Responses

Request samples

Content type
application/json
{
  • "password": "pa$$word_qwe"
}

Response samples

Content type
application/problem+json
{
  • "type": "http://example.com",
  • "title": "string",
  • "status": 100,
  • "detail": "string",
  • "instance": "string",
  • "code": "malformed_request",
  • "errors": [
    ],
  • "request_id": "string"
}

Change a user's password with the current one

Every refresh-token family of the user is revoked.

Authorizations:
apiKey
path Parameters
userId
required
string <uuid>
Request Body schema: application/json
required
current_password
required
string <password> <= 128 characters
new_password
required
string <password> (Password) [ 12 .. 128 ] characters

12–128 characters, no composition rules (ARCHITECTURE §3.8, ASVS 4.0.3 2.1.1).

Responses

Request samples

Content type
application/json
{
  • "current_password": "pa$$word",
  • "new_password": "pa$$word_qwe"
}

Response samples

Content type
application/problem+json
{
  • "type": "http://example.com",
  • "title": "string",
  • "status": 100,
  • "detail": "string",
  • "instance": "string",
  • "code": "malformed_request",
  • "errors": [
    ],
  • "request_id": "string"
}

Sign the user out everywhere

Revokes every refresh-token family. Access tokens already issued expire naturally (ADR-009).

Authorizations:
apiKey
path Parameters
userId
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "type": "http://example.com",
  • "title": "string",
  • "status": 100,
  • "detail": "string",
  • "instance": "string",
  • "code": "malformed_request",
  • "errors": [
    ],
  • "request_id": "string"
}

List an app's users (dashboard)

Authorizations:
sessionCookie
path Parameters
appId
required
string <uuid>
query Parameters
q
string <= 254 characters

Case-insensitive prefix match on email or username.

role
string <= 64 characters

Only users holding this role.

limit
integer [ 1 .. 200 ]
Default: 50
cursor
string <= 512 characters

next_cursor from the previous page.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "next_cursor": "string"
}

Get a user (dashboard)

Authorizations:
sessionCookie
path Parameters
appId
required
string <uuid>
userId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "user@example.com",
  • "username": "string",
  • "email_verified": true,
  • "roles": [
    ],
  • "metadata": { },
  • "disabled": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "last_login_at": "2019-08-24T14:15:22Z"
}

Update a user (dashboard)

Authorizations:
sessionCookie
path Parameters
appId
required
string <uuid>
userId
required
string <uuid>
Request Body schema: application/json
required
non-empty
email
string <email> <= 254 characters
username
string or null [ 3 .. 64 ] characters ^[A-Za-z0-9._-]+$
object (Metadata)

Free-form JSON object, at most 16 KiB. Not included in access tokens.

roles
Array of strings (Roles) <= 50 items unique [ items [ 1 .. 64 ] characters ^[A-Za-z0-9_:.-]+$ ]
disabled
boolean

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "username": "string",
  • "metadata": { },
  • "roles": [
    ],
  • "disabled": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "user@example.com",
  • "username": "string",
  • "email_verified": true,
  • "roles": [
    ],
  • "metadata": { },
  • "disabled": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "last_login_at": "2019-08-24T14:15:22Z"
}

Delete a user (dashboard)

Authorizations:
sessionCookie
path Parameters
appId
required
string <uuid>
userId
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "type": "http://example.com",
  • "title": "string",
  • "status": 100,
  • "detail": "string",
  • "instance": "string",
  • "code": "malformed_request",
  • "errors": [
    ],
  • "request_id": "string"
}

Sign the user out everywhere (dashboard)

Authorizations:
sessionCookie
path Parameters
appId
required
string <uuid>
userId
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "type": "http://example.com",
  • "title": "string",
  • "status": 100,
  • "detail": "string",
  • "instance": "string",
  • "code": "malformed_request",
  • "errors": [
    ],
  • "request_id": "string"
}

auth

Log an end-user in

Verifies the password and returns an access token (JWT, EdDSA) and a refresh token. Unknown identifier and wrong password are indistinguishable. Repeated failures lock the identifier (429 account_locked, Retry-After).

Authorizations:
apiKey
Request Body schema: application/json
required
identifier
required
string [ 1 .. 254 ] characters

Email or username.

password
required
string <password> [ 1 .. 128 ] characters
client_ip
string (ClientIp) <= 45 characters

The end-user's IP as seen by your backend; used for rate limiting and audit. Defaults to the connection address.

user_agent
string (ClientUserAgent) <= 512 characters

Responses

Request samples

Content type
application/json
{
  • "identifier": "string",
  • "password": "pa$$word",
  • "client_ip": "string",
  • "user_agent": "string"
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "Bearer",
  • "expires_in": 0,
  • "refresh_token": "string",
  • "refresh_expires_in": 0,
  • "user": {
    }
}

Exchange a refresh token for a new pair

Every refresh returns a new refresh token; the presented one is dead. Presenting an already-used token revokes its whole family (theft detection, ADR-011) and answers refresh_token_reused.

Authorizations:
apiKey
Request Body schema: application/json
required
refresh_token
required
string [ 1 .. 128 ] characters
client_ip
string (ClientIp) <= 45 characters

The end-user's IP as seen by your backend; used for rate limiting and audit. Defaults to the connection address.

user_agent
string (ClientUserAgent) <= 512 characters

Responses

Request samples

Content type
application/json
{
  • "refresh_token": "string",
  • "client_ip": "string",
  • "user_agent": "string"
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "Bearer",
  • "expires_in": 0,
  • "refresh_token": "string",
  • "refresh_expires_in": 0,
  • "user": {
    }
}

Revoke a refresh-token family

Authorizations:
apiKey
Request Body schema: application/json
required
refresh_token
required
string [ 1 .. 128 ] characters

Responses

Request samples

Content type
application/json
{
  • "refresh_token": "string"
}

Response samples

Content type
application/problem+json
{
  • "type": "http://example.com",
  • "title": "string",
  • "status": 100,
  • "detail": "string",
  • "instance": "string",
  • "code": "malformed_request",
  • "errors": [
    ],
  • "request_id": "string"
}

Email the end-user a password-reset link

Always 202, whether or not the email belongs to a user of this app, so the response reveals nothing. The link goes to the app's password_reset_url or the hosted page, is single-use and expires in 30 minutes. Rate limited per end-user IP (client_ip).

Authorizations:
apiKey
Request Body schema: application/json
required
email
required
string <email> <= 254 characters
client_ip
string (ClientIp) <= 45 characters

The end-user's IP as seen by your backend; used for rate limiting and audit. Defaults to the connection address.

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "client_ip": "string"
}

Response samples

Content type
application/problem+json
{
  • "type": "http://example.com",
  • "title": "string",
  • "status": 100,
  • "detail": "string",
  • "instance": "string",
  • "code": "malformed_request",
  • "errors": [
    ],
  • "request_id": "string"
}

Set a new password with a reset token

Consumes the token, sets the password, verifies the email address (the link proved control of it) and revokes every refresh-token family of the user.

Authorizations:
apiKey
Request Body schema: application/json
required
token
required
string (OneTimeToken) [ 1 .. 128 ] characters

The token query parameter of the emailed link.

new_password
required
string <password> (Password) [ 12 .. 128 ] characters

12–128 characters, no composition rules (ARCHITECTURE §3.8, ASVS 4.0.3 2.1.1).

Responses

Request samples

Content type
application/json
{
  • "token": "string",
  • "new_password": "pa$$word_qwe"
}

Response samples

Content type
application/problem+json
{
  • "type": "http://example.com",
  • "title": "string",
  • "status": 100,
  • "detail": "string",
  • "instance": "string",
  • "code": "malformed_request",
  • "errors": [
    ],
  • "request_id": "string"
}

Email the user a verification link

Works whatever the app's email_verification mode (that mode governs the automatic email on sign-up and the login check). A user who is already verified, or disabled, gets no email; the answer is 202 either way. The link goes to the app's email_verification_url or the hosted page and expires in 24 hours. Rate limited per end-user IP (client_ip).

Authorizations:
apiKey
Request Body schema: application/json
required
user_id
required
string <uuid>
client_ip
string (ClientIp) <= 45 characters

The end-user's IP as seen by your backend; used for rate limiting and audit. Defaults to the connection address.

Responses

Request samples

Content type
application/json
{
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "client_ip": "string"
}

Response samples

Content type
application/problem+json
{
  • "type": "http://example.com",
  • "title": "string",
  • "status": 100,
  • "detail": "string",
  • "instance": "string",
  • "code": "malformed_request",
  • "errors": [
    ],
  • "request_id": "string"
}

Mark the address verified with a verification token

For your own verification page (email_verification_url); the hosted page does the same.

Authorizations:
apiKey
Request Body schema: application/json
required
token
required
string (OneTimeToken) [ 1 .. 128 ] characters

The token query parameter of the emailed link.

Responses

Request samples

Content type
application/json
{
  • "token": "string"
}

Response samples

Content type
application/problem+json
{
  • "type": "http://example.com",
  • "title": "string",
  • "status": 100,
  • "detail": "string",
  • "instance": "string",
  • "code": "malformed_request",
  • "errors": [
    ],
  • "request_id": "string"
}

audit

List audit events, newest first

Authorizations:
sessionCookie
path Parameters
appId
required
string <uuid>
query Parameters
action
string <= 64 characters

Exact action name, e.g. user.created.

actor_id
string <uuid>
limit
integer [ 1 .. 200 ]
Default: 50
cursor
string <= 512 characters

next_cursor from the previous page.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "next_cursor": "string"
}