GTRADEDocs
Get started

Authentication & API keys

Every API request is authenticated with your secret merchant API key. The key also signs the webhooks sent to you.

#Sending your key

Send your API key in the Authorization header as a bearer token. The X-API-Key header is also accepted. Both forms are equivalent.

curl "https://api.gtradegateway.io/v1/payments?limit=1" \
  -H "Authorization: Bearer $GTRADE_API_KEY"

All requests must use HTTPS. GET /v1/health is the only endpoint that works without a key.

The key identifies your merchant account. You can only see and manage payments and webhook endpoints that belong to that account. Requests for another account's payment return 404, exactly like an id that does not exist.

#Creating and managing keys

Create keys in the dashboard under Developers → API Keys. Keys are long random strings; treat the whole value as opaque and do not rely on a particular format or length.

  • Use one key per environment or integration (for example one for your shop server and one for your accounting job) so that you can rotate them independently.
  • Copy the key when you create it and store it in your secret manager or as an environment variable such as GTRADE_API_KEY.

#Key security

Important: Anyone with your API key can create payments in your name, read your payment history and register webhook endpoints. Keep it on your server.

  • Never put the key in browser JavaScript, mobile apps, desktop apps or anything you ship to customers.
  • Never commit it to source control. Load it from the environment or a secret manager.
  • Don't log full request headers.
  • Restrict who can see keys in the dashboard (see team members).

#Rotating or revoking a key

  1. Create a new key in Developers → API Keys.
  2. Deploy the new key to your servers.
  3. Update your webhook signature verification to accept the new key (see below).
  4. Revoke the old key in the dashboard.

A revoked key stops working within 5 minutes. Until then it may still be accepted.

#Keys and webhook signatures

Webhook events are signed with the API key that was used to register the endpoint. If that key is revoked, events are signed with the oldest active key on your account. During a rotation, either verify against both the old and the new key, or delete and re-register your webhook endpoint with the new key. See Webhooks.

#Authentication errors

A missing, malformed or unknown key returns 401:

json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "Invalid or missing API key. Send it as \"Authorization: Bearer <api_key>\".",
    "request_id": "req_df2d07d9521d6d79"
  }
}

Repeated failed authentication from the same IP address is throttled: after 30 failures in a minute, every request from that IP receives 429 until the limit refills, even with a valid key. See Rate limits.