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.

Your scope tier controls what data you can see — it is a commercial packaging signal that filters the fields in the schema. It does not control what you are allowed to do. Actions such as writing data or administering an organisation are governed separately by capabilities and grants (the authority attached to your account), evaluated on every request. For most consumers this distinction is invisible: a std_ or edt_ key simply reads the fields its tier packages. To see the capabilities currently granted to your caller, query authzMyGrants — it returns only your own effective grants.

---

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.