Authenticate requests

Every execution request needs an API key and an HMAC signature. Agio supplies an api_token UUID and a client_secret when your partner integration is provisioned.

Sign a request

Send a JSON body containing query and, when needed, variables. Include these headers:

Header	Value
content-type	application/json
x-agio-api-key	Your api_token UUID
x-agio-timestamp	Unix time in milliseconds, represented as a decimal string
x-agio-signature	Lowercase hex HMAC-SHA256 of ${timestamp}.${rawBody}, using client_secret

rawBody is the exact UTF-8 JSON sent in the request. Whitespace, property order, and encoding affect the signature. Serialize once and use the same body for signing and sending, as shown in the quickstart.

The timestamp must be within five minutes of server time. The server accepts a (token, timestamp, signature) combination only once during a ten-minute replay window. Sign each new attempt with a fresh timestamp; after an uncertain mutation outcome, check resource or job state before retrying.

Inspect the schema

Opening the endpoint with a browser GET loads GraphiQL without authentication. Reading the schema through POST introspection requires a valid API key. Queries containing only __schema or __type selections are exempt from HMAC signing; execution queries, including __typename, are signed.

curl -sS https://dev.api.agiodigital.com/partner/cards/graphql \
  -H 'content-type: application/json' \
  -H "x-agio-api-key: $AGIO_PARTNER_API_TOKEN" \
  --data '{"query":"{ __schema { queryType { name } mutationType { name } } }"}'

The response should name Query and Mutation. GraphiQL's credential panel signs execution requests for you. Credentials entered there are held in the tab's sessionStorage.

Organization scope

The API derives your partner organization from your key. Do not send a partnerOrganizationId to select a tenant.

createPartnerCustomerOrganization returns an organizationId for a customer you manage. Supply that value as customerOrganizationId when provisioning a cardholder. It is different from your own partner organization's ID. Read queries are scoped to your managed customers; operations also check resource ownership.

Store and rotate credentials

Store client_secret in your server's secret manager. Newly issued secrets are shown once and stored encrypted by Agio. They cannot be read back through the API. Contact Agio if a secret is lost or needs rotation.

API secret rotation keeps the same API token UUID and replaces its secret immediately. There is no overlap period for API request signatures; coordinate the cutover with Agio and update your server's secret. A token can also have an expiry configured, or be revoked.

Webhook signatures use a separate secret returned by subscribePartnerWebhook. Their rotation procedure includes a 24-hour overlap; it does not apply to API credentials.

Next: Provision a cardholder.