Issue or refresh a Karmo user JWT (public — OAuth user grants only)

POST

/auth/oauth/token

Public alias. Accepts grant_type=authorization_code (used internally by /auth/callback) and grant_type=refresh_token. Hard refuses client_credentials and empty-body service-token requests — those live on the AWS_IAM-gated POST /auth/token.

Request Body ^required

object

grant_type

required

OAuth 2.0 grant type. Must be authorization_code or refresh_token.

string

Allowed values: authorization_code refresh_token

client_id

required

OAuth client id, must match an entry in the in-code client registry.

string

code

Authorization code from /auth/callback. Required when grant_type=authorization_code.

string

code_verifier

PKCE code verifier. Required when grant_type=authorization_code.

string

redirect_uri

Redirect URI from /auth/authorize. Required when grant_type=authorization_code.

string

refresh_token

WorkOS refresh token. Required when grant_type=refresh_token.

string

Responses

200

RS256 user JWT and (rotated) refresh token.

object

access_token

required

Short-lived RS256 JWT carrying the canonical user claim contract.

string

token_type

required

string

expires_in

required

Token lifetime in seconds (default 900s).

number

refresh_token

required

WorkOS refresh token (rotated value when WorkOS rotates).

string

400

BAD_REQUEST

object

type

required

string format: uri

title

required

string

status

required

integer

detail

string

instance

string

karmoCode

required

Karmo 8-digit error code.

string

/^[0-9]{8}$/

karmoMeta

Domain-level metadata emitted by the service.

object

key

additional properties

any

karmoErrors

Array<object>

object

detail

required

Human-readable detail for the specific field error.

string

pointer

required

JSON pointer to the offending value.

string

/email

401

UNAUTHORIZED

object

type

required

string format: uri

title

required

string

status

required

integer

detail

string

instance

string

karmoCode

required

Karmo 8-digit error code.

string

/^[0-9]{8}$/

karmoMeta

Domain-level metadata emitted by the service.

object

key

additional properties

any

karmoErrors

Array<object>

object

detail

required

Human-readable detail for the specific field error.

string

pointer

required

JSON pointer to the offending value.

string

/email

403

FORBIDDEN

object

type

required

string format: uri

title

required

string

status

required

integer

detail

string

instance

string

karmoCode

required

Karmo 8-digit error code.

string

/^[0-9]{8}$/

karmoMeta

Domain-level metadata emitted by the service.

object

key

additional properties

any

karmoErrors

Array<object>

object

detail

required

Human-readable detail for the specific field error.

string

pointer

required

JSON pointer to the offending value.

string

/email

404

NOT_FOUND

object

type

required

string format: uri

title

required

string

status

required

integer

detail

string

instance

string

karmoCode

required

Karmo 8-digit error code.

string

/^[0-9]{8}$/

karmoMeta

Domain-level metadata emitted by the service.

object

key

additional properties

any

karmoErrors

Array<object>

object

detail

required

Human-readable detail for the specific field error.

string

pointer

required

JSON pointer to the offending value.

string

/email

409

CONFLICT

object

type

required

string format: uri

title

required

string

status

required

integer

detail

string

instance

string

karmoCode

required

Karmo 8-digit error code.

string

/^[0-9]{8}$/

karmoMeta

Domain-level metadata emitted by the service.

object

key

additional properties

any

karmoErrors

Array<object>

object

detail

required

Human-readable detail for the specific field error.

string

pointer

required

JSON pointer to the offending value.

string

/email

422

UNPROCESSABLE_ENTITY

object

type

required

string format: uri

title

required

string

status

required

integer

detail

string

instance

string

karmoCode

required

Karmo 8-digit error code.

string

/^[0-9]{8}$/

karmoMeta

Domain-level metadata emitted by the service.

object

key

additional properties

any

karmoErrors

Array<object>

object

detail

required

Human-readable detail for the specific field error.

string

pointer

required

JSON pointer to the offending value.

string

/email

500

INTERNAL_SERVER_ERROR

object

type

required

string format: uri

title

required

string

status

required

integer

detail

string

instance

string

karmoCode

required

Karmo 8-digit error code.

string

/^[0-9]{8}$/

karmoMeta

Domain-level metadata emitted by the service.

object

key

additional properties

any

karmoErrors

Array<object>

object

detail

required

Human-readable detail for the specific field error.

string

pointer

required

JSON pointer to the offending value.

string

/email