Skip to main content
Webentor Studio

Help · API reference

Tokens

Sessions, passkeys, step-up and API tokens.

All groups

List API tokensGET /auth/tokens

Lists the caller's access tokens, one per connection, with each one's kind, grants, reach, expiry and last use; secrets are never included. An assistant token sees only itself and the assistant tokens within its reach.

Who may call it: A signed-in session, or an access token (write to change anything)

200 Success.

What comes back
  • data array of object, required

    A list of:

    • id string, required
    • name string, required
    • scopes array of string, required
    • kind "personal" | "content" | "project", required
    • door one of: "site" | "account" | null, required

      One of:

      1. "site" | "account"

      2. null

    • reach one of: "all" | "selected" | null, required

      One of:

      1. "all" | "selected"

      2. null

    • grants array of string, required
    • projects array of object, required

      A list of:

      • id string, required
      • name string, required
      • slug string, required
      • account string: The project’s team, by slug; absent for a team.
    • teams array of object, required

      A list of:

      • id string, required
      • name string, required
      • slug string, required
      • account string: The project’s team, by slug; absent for a team.
    • project_id string | null, required
    • created_at string, required: ISO 8601 timestamp.
    • last_used_at one of: string | null, required

      One of:

      1. string. ISO 8601 timestamp.

      2. null

    • expires_at one of: string | null, required

      One of:

      1. string. ISO 8601 timestamp.

      2. null

    • via "token" | "oauth", required: A pasted secret, or a client signed in through OAuth.
    • until one of: string | null, required: When it stops: the token’s expiry, or for OAuth the end of the consent.

      One of:

      1. string. ISO 8601 timestamp.

      2. null

    • status one of: "active" | "idle" | "waiting" | "expired" | null, required: An assistant token’s state; null for a personal one.

      One of:

      1. "active" | "idle" | "waiting" | "expired"

      2. null

    • rotated_at one of: string | null, required

      One of:

      1. string. ISO 8601 timestamp.

      2. null

    • client_id string | null: OAuth only: the client.
    • connected boolean | null: OAuth only: whether the connection is still live.
Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • default Any other failure, as RFC 9457 problem details.

Create an API tokenPOST /auth/tokens

Mints a token and answers 201 with its secret, shown once. With scope (read by default) it is a personal token that lives 90 days unless days says otherwise; with grants it is an assistant token that lives 24 hours unless hours says otherwise. kind, reach, projects, teams, project, account, draft and hours go only with grants.

A stepped-up session is required for: a personal token (scope); a session minting an assistant token that lives longer than a day or carries a grant beyond content, media, preview and projects:read. No access token carries step-up.

Who may call it: A signed-in session, or an access token (write to change anything)

Body (application/json)

  • name string, required, 1 to 60 characters
  • scope "read" | "write": A personal token: read reads and clones, write also changes. read when omitted.
  • grants array of "content:read" | "content" | "media" | "blocks" | "source" | "preview" | "publish" | "projects:read" | "projects" | "deploy" | "projects:delete", 1 to 11 items: An assistant token instead: its grants, from one door’s vocabulary. Not with scope.
  • kind "content" | "project": Which kind of assistant token; the grants already say.
  • reach "all" | "selected": What an assistant token reaches: everything you can open, or the projects or teams listed.
  • projects array of string (uuid), 1 to 200 items: A content token’s projects.
  • teams array of string, 1 to 50 items: A project token’s teams.
  • project string (uuid), matches ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$: One project, the shape before there was a reach.
  • account string, 1 to 80 characters: One team, the shape before there was a reach.
  • draft string (uuid), matches ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$: A draft to land the assistant on.
  • days integer, at most 365: A personal token’s life in days; 90 when omitted.
  • hours integer, at most 8760: An assistant token’s life in hours; 24 when omitted.

201 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 422 Validation failed. The body carries an issues array describing each rejected field. (code is validation_failed.)
  • default Any other failure, as RFC 9457 problem details.

Revoke an API tokenDELETE /auth/tokens/{id}

Revokes one of the caller's tokens; for a client connected through OAuth, its whole connection ends too (connection_ended). An assistant token may revoke only itself and assistant tokens within its reach.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • id (path, string)

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 404 Not found. Also returned when the resource exists but the caller may not see it, so that the two cannot be told apart. (code is not_found.)
  • 422 Validation failed. The body carries an issues array describing each rejected field. (code is validation_failed.)
  • default Any other failure, as RFC 9457 problem details.