Prove a fresh re-authentication (step-up)

POST

/api/v1/me/step-up

curl --request POST \
  --url https://api.deploybase.eu/api/v1/api/v1/me/step-up \
  --header 'Authorization: <Authorization>' \
  --header 'Content-Type: application/json' \
  --data '{ "session_id": "312909075212468632", "session_token": "yMDi6uVPJAcphbbz0LaxC07ihWkNTe7m0Xqch8SzfM5Cz3HSIQIDZ65x1f5Qal0jxz0MEyo-_zYcUg" }'

Exchanges a Zitadel session the caller has just authenticated (password plus TOTP when enrolled, a passkey with user verification, or an identity provider) for a single-use 10-minute grant that unlocks one sensitive account change. The response’s grant_token is shown only once and only to this caller: the client must keep it and send it as the X-Deploybase-Step-Up header on the guarded request (for example POST /api/v1/me/email-change); without it the guarded request is refused with REAUTH_REQUIRED. The session must belong to the signed-in user and its credential checks must be at most 10 minutes old; it is deleted afterwards and can be used once. Limited to 10 attempts per user per hour. Requires a signed-in person: API keys are refused.

Authorizations

• BearerAuth

Request Body

The freshly authenticated Zitadel session

Media type application/json

object

session_id

string

Example

312909075212468632

session_token

string

Example

yMDi6uVPJAcphbbz0LaxC07ihWkNTe7m0Xqch8SzfM5Cz3HSIQIDZ65x1f5Qal0jxz0MEyo-_zYcUg

Responses

200

OK

Media type application/json

object

data

meta

object

request_id

string

timestamp

string

trace_id

string

data

object

expires_at

string

factors

Array<string>

grant_token

string

Example

{
  "data": {
    "expires_at": "2026-10-03T12:10:00Z",
    "factors": [
      "password",
      "totp"
    ],
    "grant_token": "q3Xv0bT9mJ2pLr8cWn5ZyK1eHs7AdUf4GiOx6VtRlEw"
  }
}

400

Malformed body, or the session is invalid, foreign or already used (STEP_UP_INVALID)

Media type application/json

object

code

string

details

error

string

meta

object

request_id

string

timestamp

string

trace_id

string

Example ^generated

{
  "code": "example",
  "details": "example",
  "error": "example",
  "meta": {
    "request_id": "example",
    "timestamp": "example",
    "trace_id": "example"
  }
}

401

Unauthorized

Media type application/json

object

code

string

details

error

string

meta

object

request_id

string

timestamp

string

trace_id

string

Example ^generated

{
  "code": "example",
  "details": "example",
  "error": "example",
  "meta": {
    "request_id": "example",
    "timestamp": "example",
    "trace_id": "example"
  }
}

403

REAUTH_REQUIRED (factors too weak), STEP_UP_UNSUPPORTED or HUMAN_SESSION_REQUIRED

Media type application/json

object

code

string

details

error

string

meta

object

request_id

string

timestamp

string

trace_id

string

details

object

required

string

Allowed values: any mfa

Example

{
  "details": {
    "required": "any"
  }
}

429

Too many attempts; see Retry-After

Media type application/json

object

code

string

details

error

string

meta

object

request_id

string

timestamp

string

trace_id

string

Example ^generated

{
  "code": "example",
  "details": "example",
  "error": "example",
  "meta": {
    "request_id": "example",
    "timestamp": "example",
    "trace_id": "example"
  }
}

500

Internal Server Error

Media type application/json

object

code

string

details

error

string

meta

object

request_id

string

timestamp

string

trace_id

string

Example ^generated

{
  "code": "example",
  "details": "example",
  "error": "example",
  "meta": {
    "request_id": "example",
    "timestamp": "example",
    "trace_id": "example"
  }
}