API Key Management

What a key looks like

An API key authenticates every Customer API request. It is 56 characters and always has the same shape:

gsk_a1b2c3d4_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
│    │        │
│    │        └─ 43-character secret
│    └─ 8-character key id - safe to log, safe to show
└─ prefix, always gsk_

Send it as a bearer token: Authorization: Bearer gsk_....

The full key is shown once, on the screen where you create it. It is stored only as a one-way hash, so nobody - including GameGrid support - can show it to you again. If you lose it, create a new key and revoke the old one.

Creating a key

Keys are created and destroyed in the customer panel, under Account → API Keys, signed in as yourself. This is deliberate: there is no scope that lets an API key create another API key, so a leaked key cannot mint a broader or longer-lived successor.

1. Open Account → API Keys and choose Create Key.

2. Give it a name that says what it is for. nightly-backup-script will still mean something in six months; test2 will not. Names must be unique within your organization.

3. Choose an expiry. 1 to 365 days, or no expiry. If you leave it alone the key expires in 90 days.

4. Pick the scopes. Grant the smallest set that lets the job finish - see API Scopes and Permissions.

5. Optionally restrict the key to specific servers. A restricted key gets 404 server_not_found for anything outside its list - the same response as a server that does not exist, so the key cannot be used to discover what else you own.

6. Copy the key. This is the only time it is shown.

You can only grant scopes you personally hold. Asking for more returns 422 scope_exceeds_permissions - which is usually a sign you are creating the key from the wrong account.

One key per job

The single most useful habit with API keys is to stop having one key that does everything.

Separate keys mean you can revoke a compromised integration without taking down the other five; the audit trail tells you which integration did something, not just "a key did"; and each key carries only the scopes its own job needs, so a leaked status-page key cannot wipe a server.

Restrict by server as well as by scope where it fits. A key for one community's Minecraft server has no business seeing your other servers.

Rotating a key

Rotation replaces a key's secret without changing what the key is allowed to do. Use it on a schedule, when someone leaves, or any time you are not certain where a key has been.

Rotate from Account → API Keys → Rotate. You choose a grace period: 24 hours by default, up to 7 days, or 0 for an immediate cutover.

That overlap is the point - deploy the new key, confirm everything is running on it, and let the old one lapse. With a 0-hour grace the old key stops working the moment you rotate, which is what you want if you believe it has leaked.

Rotation carries over the key's name, description, scopes, expiry date and every server restriction. Rotation does not carry over the secret (a brand-new one is minted) or the 8-character key id - so any logging or dashboard that matches on the key id needs updating.

Rotation is a panel action. There is no API endpoint that rotates a key, by design.

Revoking a key

Revoking is immediate and permanent. A revoked key cannot be restored; create a new one instead. Revoked keys take effect within about a minute across the platform.

From the panel

Delete the key in Account → API Keys. This works for any key in your organization and is the normal route.

From the key itself

A key can switch itself off:

DELETE /api/public/v1/account/keys/{its own key id}
Authorization: Bearer gsk_...

This is a containment tool. A script that detects it has been compromised can kill its own access at 3am without waiting for a human to sign in.

Two things to get right before you rely on it. The key must hold the keys:revoke scope - without it the call returns 403 insufficient_scope. And a key can only revoke itself: passing any other key id returns 403 insufficient_scope with the rule self_revocation_only, even if you own that other key. If self-revocation is part of your incident plan, put keys:revoke on the key when you create it and test the call once.

If a key leaks

Work in this order.

1. Revoke it. Panel, or the key's own DELETE /account/keys/{keyId} if it holds keys:revoke. Do this before investigating - a revoked key cannot do further damage while you read logs.

2. Read the audit trail. GET /account/audit (scope audit:read) covers a rolling 24-hour window and records every Customer API call made with your organization's keys - including calls that were rejected - alongside panel actions on your servers. Rejected calls matter: they show what an attacker tried and failed to do, which tells you what they were after.

3. Check where it was last used. GET /account/keys reports last_used_at and last_used_ip for each key. An unfamiliar address narrows the window.

4. Check what changed. Settings history (GET /servers/{id}/settings/history), backups, mods and player lists all keep their own records. Restore from a backup taken before the window if anything is wrong.

5. Create the replacement with narrower scopes than the one that leaked. A leak is the best evidence you will ever get about which scopes a job actually needed.

The audit trail is your detection tool for key misuse. Webhooks are not - there is no event for "a key did something unexpected", and no webhook fires on a wipe or a reinstall. Poll GET /account/audit on a schedule if you want alerting. See Webhook Configuration for what webhooks can and cannot tell you.

Checking what a key can do

GET /account/keys/current returns the calling key's own record - its id, name, scopes, expiry, server restrictions and last use. It needs no scope, precisely so that a key with a mistyped scope list can still discover what it holds.

Two fields in that response are worth reading in a deploy check:

• unrecognized_scopes - scope strings written on the key that the platform does not recognise. Usually a typo, and always worth fixing, because a typo'd scope grants nothing.
• server_restrictions - the servers this key is limited to, if any.

If a call fails, this endpoint plus GET /servers/{id}/capabilities will explain almost every 403 and 501 without a support ticket.

Key expiry and hygiene