POST /token — Create a scoped API token

POST https://api.sandbox-gameye.gameye.net/token

Creates a new API token with a specified set of scopes and optional expiry. The calling token can only grant scopes it already holds — it cannot create a token with broader permissions than itself. The one exception is webhook:github: any token with token:write can grant it, so you can create a GitHub webhook secret without holding that scope yourself.

Requires the token:write scope on the calling token.

Request Body

Field	Type	Required	Description	Example
name	string	Yes	A human-readable name for this token. Must be unique among the tokens of the user that owns the calling token.	"match-server-token"
scopes	array	Yes	The list of permission scopes to assign to the new token.	["session:start", "session:read"]
expires_after	string	No	How long until the token expires, as a duration string with units m and h, e.g. "30m", "1h", "2.5h", "2h30m". Values under a minute (including "0m") are rounded up to a minute. Negative values are rejected. Omit the field, or send an empty string, for a non-expiring token.	"2h"

The field name is expires_after (snake_case). Unknown fields are ignored, so a misspelt name such as expiresAfter creates a token that never expires. If the duration can’t be parsed, the 400 response names the field expiresAfter in its violations list.

Available Scopes

Scope	Description
session:start	Start new game sessions
session:read	List and describe sessions
session:stop	Stop running sessions
artifact:read	Download session artifacts
logs:read	Stream session logs
session:write	Register players joining and leaving a session
regions:read	Check image and tag availability, and enable application tags
region:read	List regions (GET /region)
token:write	Create new tokens (delegation)
application:read	List applications and registry tags
application:write	Create and modify applications
webhook:dockerhub	Authenticate Docker Hub webhook deliveries
webhook:github	Sign GitHub Container Registry webhook deliveries. Use this token as the webhook secret; see Getting started with GHCR.

Requesting a scope that doesn’t exist returns 400.

Code Examples

cURL

curl -X POST 'https://api.sandbox-gameye.gameye.net/token' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "name": "match-server-token",
  "scopes": ["session:start", "session:read"],
  "expires_after": "2h"
}'

JavaScript

const response = await fetch('https://api.sandbox-gameye.gameye.net/token', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'match-server-token',
    scopes: ['session:start', 'session:read'],
    expires_after: '2h',
  }),
});
const { token } = await response.json();

Python

import requests

response = requests.post(
    'https://api.sandbox-gameye.gameye.net/token',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
    json={
        'name': 'match-server-token',
        'scopes': ['session:start', 'session:read'],
        'expires_after': '2h',
    },
)
token = response.json()['token']

Responses

201

A new API token was successfully created. This is the only API response that contains the token value, so store it securely straight away.

Field	Type	Required
token	string	Yes

{
  "token": "3f2c8a9e-6b1d-4c7a-9e2f-8d5b1a0c4e7f"
}

400

Invalid request body (including malformed JSON), duration format, or scope name.

401

You are not authorized. Make sure your bearer token is correct, active, and not expired.

403

The calling token doesn’t have the token:write scope, or it doesn’t hold one or more of the requested scopes and can’t delegate them.

413

The request body exceeds 64 KiB.

500

Internal error. A duplicate token name currently returns this status rather than 409; choose a new name and retry.