Authentication

The Podium GraphQL API uses API key authentication for API calls. Human access to the developer portal uses either:

• A self-serve email/password account
• Podium SSO for internal staff

Once you are in the portal, every API request still carries a key in the x-api-key HTTP header.

---

Sending the API key

Pass your key in the x-api-key header on every request:

curl

curl -X POST https://api.podium.pagroup.com/graphql \
  -H "Content-Type: application/json" \
  -H "x-api-key: std_your_key_here" \
  -d '{"query":"{ __typename }"}'

JavaScript (fetch)

const response = await fetch('https://api.podium.pagroup.com/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': process.env.PODIUM_API_KEY,
  },
  body: JSON.stringify({ query: '{ __typename }' }),
});
const { data } = await response.json();

Python (httpx)

import httpx, os

client = httpx.Client(
    base_url="https://api.podium.pagroup.com",
    headers={"x-api-key": os.environ["PODIUM_API_KEY"]},
)
resp = client.post("/graphql", json={"query": "{ __typename }"})
print(resp.json())

---

Scope tiers

API keys are issued with one of three scope tiers. The tier controls which fields are visible in GraphQL responses.

Tier	Key prefix	Fields available
Standard Card	std_	Race card data: meetings, races, runners, SP, draw, weight, form
Editorial Card	edt_	Standard + editorial fields: tips, verdicts, forecast/ESP prices, close-up comments
Internal API	int_	Full schema including write mutations (Podium internal use only)

Fields outside your tier’s scope are removed from the schema entirely — they will not appear in introspection and cannot be queried. The server pre-builds a filtered schema per tier at startup.

Caution

Never embed an int_ key in client-side code or public repositories. Treat it like a root password.

Note

Internal API keys (int_) are bound to a synthetic platform-admin identity. This grants full schema access including write mutations — they are intended for Podium-operated services only and are not customer-managed.

---

Rate limits

Rate limits are enforced per key and reset on a rolling one-hour window.

Tier	Requests / hour
Standard Card	1 000
Editorial Card	5 000
Internal API	50 000

When a limit is exceeded the API returns HTTP 429 Too Many Requests with a Retry-After header indicating seconds until the window resets.

---

Key lifecycle

Creating a key

1. Sign in to the developer portal.
2. Create or join an organisation.
3. Navigate to Organisations → API Keys → Generate key.
4. Choose a scope tier and environment.
5. Copy the key — it is shown once only. The server stores only a secure hash.

Note

Self-serve organisations can create keys up to their organisation’s entitled scope tier. Internal-only tiers are not customer-managed.

Revoking a key

Go to Organisations → API Keys, find the key, and select Revoke. Revocation takes effect within one second (NFR-003). Any in-flight requests using the revoked key will be rejected on their next validation.

Rotating a key

When you rotate a key, the system:

1. Issues a new key immediately.
2. Sets a 24-hour grace period on the old key so existing integrations have time to update.
3. After 24 hours, the old key is permanently invalidated.

To rotate:

1. Go to Organisations → API Keys.
2. Select the key and click Rotate.
3. Copy the new key and update your integrations.
4. Confirm rotation — the grace period starts.

Tip

Store keys in environment variables or a secrets manager (AWS Secrets Manager, HashiCorp Vault). Never hard-code them in source files.

---

Request logging

Every authenticated request generates a structured log entry tied to your key ID. Logs include:

• operation — the GraphQL operation name (use named operations for better observability)
• latency_ms — end-to-end response time in milliseconds
• status — success or error

Your organisation’s audit log is available in the developer portal alongside your key management screens.