Tokens

Tokens authenticate API requests. Every token carries a permission map that limits what resource kinds it can read or write. The plaintext code is returned exactly once at creation; the server stores only a SHA-256 hash of it, so you cannot retrieve it again.

There are three token subjects:

Subject	Bound to	Created by
USER	A user account	POST /v1/tokens or POST /v1/users/{uid}/tokens
WORKSPACE	A workspace	POST /v1/workspaces/{wid}/tokens
RESOURCE	One resource inside a workspace	POST /v1/workspaces/{wid}/tokens with subject and subject_id

Session tokens (origin: SESSION) are minted at login and cannot be created through the API. They carry unrestricted grants and can be refreshed within the last six hours of their lifetime.

---

Create a token (caller shorthand)

POST/v1/tokensCreate a USER-scope token for the authenticated user

Alias for POST /v1/users/@me/tokens. Creates a USER-subject API token bound to the authenticated user. The token can reach every workspace the user can access, gated by the supplied permission map.

Request body

Field	Type	Required	Description
name	string	yes	Token name, 4-48 characters
expires	string (ISO 8601)	yes	Expiration timestamp
grants	object	yes	Map of resource kind to permission level. Keys: WORKSPACE, INSTANCE, DEDIBOX, APP, IMAGE, NET_BALANCER, DISK, FLOATING_IP. Values: NONE, READ, or WRITE.

curl -X POST https://api.galaxygate.net/v1/tokens \
  -H "Authorization: Bearer $GALAXYGATE_TOKEN" \
  -H "Content-Type: application/json" \
  -A 'curl/8.5' \
  -d '{
    "name": "ci-deploy",
    "expires": "2027-01-01T00:00:00Z",
    "grants": {
      "WORKSPACE": "READ",
      "INSTANCE": "WRITE",
      "IMAGE": "READ"
    }
  }'

Returns a token creation response (see Token creation response).

Create a USER-scope token

POST/v1/users/{uid}/tokensCreate a USER-scope API token

Creates a USER-subject API token bound to the given user. The uid must match the authenticated user; @me is accepted as an alias for the current user's ID.

Path parameters

Name	Type	Description
uid	integer or @me	User ID

Request body - same as POST /v1/tokens above.

Returns a token creation response.

List user tokens

GET/v1/users/{uid}/tokensList user-scope tokens

Lists USER-subject tokens (both SESSION and API origin) bound to the given user account.

Path parameters

Name	Type	Description
uid	integer or @me	User ID

Query parameters

Name	Type	Description
q	string	Quick search by name or ID
id	integer[]	Filter to specific token IDs
name	string	Filter by name
origin	string	Filter by origin: SESSION, API, SYSTEM, or OAUTH
subject	string	Filter by subject: USER, WORKSPACE, or RESOURCE

Plus the shared pagination parameters. Returns a paged list of token objects.

Revoke all user sessions

DELETE/v1/users/{uid}/tokensRevoke all user sessions

Revokes all active SESSION-origin tokens for the given user. API tokens are not touched. Useful for forcing a global sign-out after a password change or suspected compromise.

Path parameters

Name	Type	Description
uid	integer or @me	User ID

Returns 202 Accepted with an empty body.

Fetch a token

GET/v1/tokens/{id}Fetch a token

Returns metadata for a single token. USER-subject tokens are visible to their owning user. Workspace and resource tokens are visible to any EDITOR or above on the owning workspace. The plaintext code is never returned.

Path parameters

Name	Type	Description
id	integer	Token ID

Returns a token object (see Token object).

Delete a token

DELETE/v1/tokens/{id}Delete a token

Deletes a token, immediately invalidating it. USER-subject tokens can be deleted by their owning user. Workspace and resource tokens require the Administrator role on the owning workspace.

Path parameters

Name	Type	Description
id	integer	Token ID

Returns 202 Accepted with an empty body.

Refresh a session token

POST/v1/tokens/refreshRefresh a session token

Resets the expiration of a SESSION-origin token. The token must not be expired and must be within the last six hours of its lifetime (the refresh window). Only SESSION tokens can be refreshed; API tokens cannot.

Request body

Field	Type	Required	Description
code	string	yes	Plaintext session token code to refresh

Returns an object with a single field:

Field	Type	Description
expires	string (ISO 8601)	New expiration timestamp

---

Workspace token endpoints

List workspace tokens

GET/v1/workspaces/{wid}/tokensList workspace-scope tokens

Lists tokens that belong to a workspace or any of its resources. Requires at least the Editor role on the workspace.

Path parameters

Name	Type	Description
wid	integer	Workspace ID

Query parameters - same as List user tokens above.

Plus the shared pagination parameters. Returns a paged list of token objects.

Create a workspace or resource token

POST/v1/workspaces/{wid}/tokensCreate a workspace-scope or resource-scope token

Creates a token bound to a workspace or to one of its resources. Requires the Administrator role.

For a workspace-scoped token, omit subject and subject_id (or send subject: "WORKSPACE"). For a resource-scoped token, set subject to RESOURCE and provide subject_id with the ID of the resource; the resource must belong to the path workspace.

Path parameters

Name	Type	Description
wid	integer	Workspace ID

Request body

Field	Type	Required	Description
name	string	yes	Token name, 4-48 characters
expires	string (ISO 8601)	yes	Expiration timestamp
grants	object	yes	Map of resource kind to permission level (see Create a token for keys and values)
subject	string		WORKSPACE (default) or RESOURCE
subject_id	integer		ID of the resource to pin the token to. Required when subject is RESOURCE. Valid resource kinds for resource-scope: INSTANCE, DEDIBOX, APP.

curl -X POST https://api.galaxygate.net/v1/workspaces/42/tokens \
  -H "Authorization: Bearer $GALAXYGATE_TOKEN" \
  -H "Content-Type: application/json" \
  -A 'curl/8.5' \
  -d '{
    "name": "instance-reader",
    "expires": "2027-06-01T00:00:00Z",
    "grants": {
      "INSTANCE": "READ"
    },
    "subject": "RESOURCE",
    "subject_id": 101
  }'

Returns a token creation response.

---

Token creation response

The response from any create endpoint includes a code field containing the plaintext token. This is the only time it is exposed.

Field	Type	Description
id	string	Token ID
name	string	Token name
created	string (ISO 8601)	When the token was created
expires	string (ISO 8601)	When the token expires
origin	string	How the token was created: SESSION, API, SYSTEM, or OAUTH
subject	string	What the token is bound to: USER, WORKSPACE, or RESOURCE
subject_id	string	ID of the bound entity
workspace_id	string	Workspace the token can reach (null for USER-subject tokens)
grants	object	Resource kind to permission level map
code	string	Plaintext token. Save this securely; it is never returned again.

Token object

Returned by fetch and list endpoints. Identical to the creation response except code is absent.

Field	Type	Description
id	string	Token ID
name	string	Token name
created	string (ISO 8601)	When the token was created
expires	string (ISO 8601)	When the token expires, or null for non-expiring tokens
origin	string	SESSION, API, SYSTEM, or OAUTH
subject	string	USER, WORKSPACE, or RESOURCE
subject_id	string	ID of the bound entity
workspace_id	string	Workspace the token can reach, or null
grants	object	Resource kind to permission level map
user	object	User account that owns this token (USER-subject only)
created_by	object	User who created the token
last_ip	string	Last IP address that used this token
last_used	string (ISO 8601)	Last time this token was used