Authenticate a user and manage the session

This guide walks through the full session lifecycle in iam: authenticate to get a token pair, use the access token, refresh it before it expires, list your active sessions, and revoke one when you’re done.

Before you begin

• Prerequisites. An active User with a valid email and password, and the base URL https://api.qibdo.example.com.
• Concepts. For the model behind tokens, see session tokens.

Your deployment’s API domain

api.qibdo.example.com is an example host. qibdo runs on your own infrastructure, so the API lives at your deployment’s own domain. Replace it with yours before running these examples.

Console

Coming soon

A step-by-step walkthrough in the qibdo console is on the way. For now, use the REST tab.

CLI

Coming soon

A qibdo CLI walkthrough is on the way. For now, use the REST tab.

REST

Step 1: Authenticate

Send the user’s email and password to the authenticate endpoint. This endpoint does not require a bearer token.

POST /iam/v1/users:authenticate HTTP/1.1
Host: api.qibdo.example.com
Content-Type: application/json

{
  "email": "engineer@example.com",
  "password": "$QIBDO_USER_PASSWORD"
}

The response carries the access/refresh pair, their expiry timestamps, and the access token’s hash:

{
  "access_token": "$QIBDO_API_TOKEN",
  "access_token_expires_at": "2026-06-02T13:00:00Z",
  "refresh_token": "$QIBDO_REFRESH_TOKEN",
  "refresh_token_expires_at": "2026-06-09T12:00:00Z",
  "access_token_hash": "a1b2c3d4e5f6..."
}

Capture the access token into an environment variable so it never appears in a command line:

export QIBDO_API_TOKEN="<the access_token from the response>"
export QIBDO_REFRESH_TOKEN="<the refresh_token from the response>"

Step 2: Use the access token

Present the access token as a bearer credential on any authenticated request, for example listing users:

GET /iam/v1/users HTTP/1.1
Host: api.qibdo.example.com
Authorization: Bearer $QIBDO_API_TOKEN

Step 3: Refresh before expiry

When the access token’s expiry is near, exchange the refresh token for a fresh pair at the refresh endpoint. This consumes the old refresh token, so replace both stored values with the new ones from the response.

POST /iam/v1/tokens:refresh HTTP/1.1
Host: api.qibdo.example.com
Content-Type: application/json

{
  "refresh_token": "$QIBDO_REFRESH_TOKEN"
}

The response has the same shape as the authenticate step: a new access token, refresh token, their expiry timestamps, and the new hash.

Step 4: List your active sessions

Listing tokens returns the authenticated user’s active sessions. Each one shows its hash, its metadata (the source IP and user agent it was created from), and its expiry, useful for spotting a session you don’t recognise.

GET /iam/v1/tokens?page_size=20 HTTP/1.1
Host: api.qibdo.example.com
Authorization: Bearer $QIBDO_API_TOKEN

Step 5: Revoke a session

To log out the current session, send an empty body to the revoke endpoint. iam revokes the bearer credential from the Authorization header (recorded as a self-revoke).

POST /iam/v1/tokens:revoke HTTP/1.1
Host: api.qibdo.example.com
Authorization: Bearer $QIBDO_API_TOKEN
Content-Type: application/json

{}

To revoke a specific session, for example one you spotted in step 4, send its hash:

POST /iam/v1/tokens:revoke HTTP/1.1
Host: api.qibdo.example.com
Authorization: Bearer $QIBDO_API_TOKEN
Content-Type: application/json

{
  "token_hash": "a1b2c3d4e5f6..."
}

Revoking a token cascades to its sibling tokens in the same family. The call returns an operation acknowledging the revoke; if the hash does not exist or you aren’t allowed to see it, the call returns NOT_FOUND.

Next steps

• Learn what your authenticated identity can do in the authorization model.