Use an API key
Exchange an organization API key for a short-lived access token and call a GraphxServer.io API with it.
Draft
This page is unfinished. The sections marked "To be written" are waiting on details from the API team. What's here already matches the current identity server code.
The GXSIO API also accepts the key directly as Authorization: Bearer <key>, without the exchange below. The GXSIO API reference shows how. Which approach integrations should use is still to be confirmed.
You don't send the API key to an API on every request. Your integration trades the key for a short-lived access token at the identity server, then calls the API with that token. When the token expires, it trades the key again.
This keeps the long-lived secret in one place. The API only ever sees a token that expires on its own, and if one leaks it stops working quickly.
Your integration --(API key + client credentials)--> Identity server
Your integration <------------(access token)-------- Identity server
Your integration --------(Bearer access token)-----> GraphxServer.io APIWhat you need
- An API key from Create and manage API keys. It starts with
GXS_O-. - An OAuth client registered for token exchange, with its client ID and secret. Keys don't replace client authentication, so the identity server needs both. To be written: who registers this client and how to ask for one.
- The resource URI of the API you're calling, such as
https://dev.api.graphxserver.io/orders, and the scopes it requires.
Exchange the key for a token
The exchange is a POST to the identity server's token endpoint. The full parameter list is in Exchange an organization API key. Here's the shape of the request.
curl --fail-with-body \
--request POST "https://dev.auth.graphxserver.io/api/auth/oauth2/token" \
--user "$CLIENT_ID:$CLIENT_SECRET" \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
--data-urlencode "subject_token=$GXS_API_KEY" \
--data-urlencode 'subject_token_type=urn:graphxsource:params:oauth:token-type:api-key' \
--data-urlencode 'requested_token_type=urn:ietf:params:oauth:token-type:access_token' \
--data-urlencode 'resource=https://dev.api.graphxserver.io/orders' \
--data-urlencode 'scope=orders.read'Load GXS_API_KEY, CLIENT_ID and CLIENT_SECRET from your secret store. Don't paste them into the command, where they'd end up in your shell history.
Call the API
To be written: a request to a real GraphxServer.io endpoint with the token in the Authorization: Bearer header, plus a sample response.
Refresh the token
To be written: how long tokens last and when to request a new one.
What the key can reach
To be written: which scopes an organization key can request, and how the permission level chosen in settings will relate to them.
Errors
To be written: common failures for this flow. Until then, see the identity server troubleshooting table.