Copy page

Getting Started

API Keys

API Keys are the credentials used for admin-level server-to-server authentication with the Gamopanda API. Each key pair consists of an apiKey identifier and an apiSecret — both generated by the platform on creation. They are sent as request headers (x-api-key and x-api-secret) on every admin API call.

---

How it works

1. Create an API key — provide a name and optional description. The platform generates the apiKey and apiSecret values automatically and returns the secret in the creation response.
2. Store the secret securely — copy the apiSecret from the response and store it in your secrets manager or environment variables. It will not be shown again.
3. Authenticate requests — include both values as headers on every admin API call:

   Code
   x-api-key: <your-api-key>
   x-api-secret: <your-api-secret>

4. Rotate when needed — delete the old key and create a new one to rotate credentials. Update your services with the new apiSecret before deleting the old key.
5. Revoke instantly — set status to paused to disable a key without deleting it, or DELETE to remove it permanently.

---

Fields

Field	Type	Required	Notes
name	string	✅	A unique, human-readable label for this key. Max 256 chars.
description	string	❌	Optional notes about what this key is used for. Max 1 024 chars.
apiKey	string	—	System-generated identifier. Read-only. Max 32 chars. Returned on every GET.
apiSecret	string	—	System-generated secret. Read-only. Max 64 chars. Returned on POST (create) only — never again.
status	enum	✅	draft · live · paused. Only live keys are accepted for authentication.

---

Creating an API key

Code
POST /api/v1.0/schema/apikey/record
x-api-key: <existing-api-key>
x-api-secret: <existing-api-secret>

{
  "name": "Production Server Key",
  "description": "Used by the order service to log streak and challenge activity",
  "status": "live"
}

---

Using the key to authenticate

Once created, include both values as HTTP headers on all admin API requests:

Code
GET /api/v1.0/schema/streak/record
x-api-key: abc123def456
x-api-secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

---

Rotating a key

To rotate credentials without downtime:

1. Create a new key — POST /schema/apikey/record with a new name.
2. Deploy the new credentials — update x-api-key / x-api-secret in all services that use the old key.
3. Verify — confirm all services are using the new key successfully.
4. Delete the old key — DELETE /schema/apikey/record/{old-key-id}.

---

Revoking a key

To temporarily suspend a key without deleting it:

Code
PATCH /api/v1.0/schema/apikey/record/{id}
x-api-key: <admin-key>
x-api-secret: <admin-secret>

{
  "status": "paused"
}

Requests using a paused or draft key will be rejected with 401 Unauthorized.

---

Access & permissions

Caller	Allowed operations	Notes
Admin	CREATE · GET · LIST · UPDATE · DELETE	Full control — admin credentials required for all operations
End user	(none)	Not accessible
Guest user	(none)	Not accessible

---

Security best practices

• Never expose credentials in client-side code — API keys are for server-to-server calls only. The end-user widget uses x-enduser-access-token and x-account-id instead.
• One key per service — create a separate key for each service or environment (staging, production) so you can rotate or revoke them independently.
• Least privilege by name — while all admin keys have the same permissions, naming them clearly (e.g. "order-service-prod") makes audit logs easier to trace.
• Rotate regularly — establish a rotation policy (e.g. every 90 days) and use the rotation workflow above.

---

Related resources

Resource	Description
Introduction	Overview of both authentication flows — admin (x-api-key / x-api-secret) and end-user (x-enduser-access-token / x-account-id)

---

API reference

See the API Reference for full request/response schemas and interactive examples for:

• GET /schema/apikey/record — list API keys
• POST /schema/apikey/record — create an API key
• GET /schema/apikey/record/{id} — get an API key by ID
• PATCH /schema/apikey/record/{id} — update an API key
• DELETE /schema/apikey/record/{id} — delete an API key