StarMeUp OS

Token Operations

Token lifecycle operations

Operations

We expose the following operations listed below:

Revoke

Invalidates the token sent in the request (a.k.a. logout). After this call the token can no longer be used to authenticate against any /os-api/** endpoint; subsequent calls with the same token will be rejected with 401 Unauthorized.

  • The token to invalidate must be sent in the Authorization header as a Bearer token.

  • The operation is idempotent: invalidating an already-invalid token returns 200 OK.

  • The verb is POST to align with OAuth2 RFC 7009 — OAuth 2.0 Token Revocation.

Resource URL

POST: /os-api/public-api/v1/token/revoke

Header Parameters

Parameter Optional/Required Description

Authorization

Required

Bearer token to be invalidated (You can get information on Authentication).

Response

HTTP/1.1 200 OK

Example: 

  {
    "message": "Token successfully invalidated"
  }

Errors

HTTP/1.1 400 Bad Request, 401 Unauthorized, 403 Forbidden, 500 Internal Server Error

Example: 

  {
    "timestamp": "2026-05-19",
    "message": "Unauthorized",
    "details": "The provided token is malformed or missing",
    "type": "uri=/os-api/public-api/v1/token/revoke",
    "title": "Unauthorized",
    "detail": "Authentication is required to access this resource."
  }

Refresh token

Exchanges a refresh token for a brand-new access token (and a rotated refresh token). The received refresh token is invalidated as part of the operation; only the returned access_token/refresh_token should be used after this call.

This endpoint is inspired by OAuth2 RFC 6749 §6 but uses a JSON body instead of application/x-www-form-urlencoded, in line with the rest of this Public API. Both grant_type and refresh_token must travel in the JSON request body — they are not read from query parameters.

  • If the received refresh token is expired, revoked, or unknown, the call returns 400 Bad Request with an invalid_grant error per RFC 6749 §5.2.

Resource URL

POST: /os-api/public-api/v1/token

Header Parameters

Parameter Optional/Required Description

Authorization

Required

Bearer application token (You can get information on Authentication).

Content-Type

Required

application/json

Request Body

Parameter Optional/Required Description

grant_type

Required

Must be the literal string refresh_token.

refresh_token

Required

The refresh token previously issued.

Example: 

  {
    "grant_type": "refresh_token",
    "refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJqdGkiO..."
  }

Example Curl: 

  curl --request POST \
    --url '/os-api/public-api/v1/token' \
    --header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJqdGkiO...' \
    --header 'Content-Type: application/json' \
    --data '{
      "grant_type": "refresh_token",
      "refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJqdGkiO..."
  }'

Response

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

Example: 

  {
    "access_token": "eyJhbGciOiJIUzUxMiJ9.eyJqdGkiOiIu...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA-rotated"
  }

Errors

HTTP/1.1 400 Bad Request, 401 Unauthorized, 500 Internal Server Error

Example (error response): 

  {
    "error": "invalid_grant",
    "error_description": "The provided refresh token is expired or has already been used."
  }