Skip to main content
API key pairs are used to sign the JSON Web Tokens (JWTs) that authenticate your server-side calls to the Gr4vy API. You can create and manage them from the dashboard, under Integrations > API Keys. To manage keys programmatically instead, see Managing API keys.

​
Create an API key

  1. Go to Integrations > API Keys.
  2. Select Add an API key.
  3. Enter a Name to identify the key, for example Web API key.
  4. Choose the Permissions for the key. This sets the key’s roles:
    • Full access allows the key to process payments, manage connections, edit Flow rules, and more.
    • Processing only allows the key to process payments, including managing payment methods and buyers.
    • System management only allows the key to manage connections and edit Flow rules.
    • Transaction reporting only allows the key to read payments data, including creating and accessing reports.
    • Key management only allows the key to manage API keys, including creating, editing, and activating or deactivating keys.
    You can select more than one, in which case the key has the combined access of each. Key management only grants no access on its own, so it has to be combined with another permission.
  5. Choose the Algorithm. ECDSA is recommended. Only use RSA in environments that do not support ECDSA.
  6. Under Merchants, either grant the key access to all merchant accounts or select specific merchant accounts.
  7. Select Create API key.
Gr4vy generates the key pair and provides the private key once, when the key is created. Store the private key securely, as it cannot be retrieved again.
When a key has access to more than one merchant account, set the X-Gr4vy-Merchant-Account-Id header on every request, or merchantAccountId in Embed. Without it, the request uses the default merchant account and returns a 403 error if the key has no access to that account. A key scoped to a single merchant account always uses that account and ignores the header.

​
Manage API keys

The API Keys table lists each key with its name, roles, algorithm, merchant access, when it was last used, creator, and creation date. The Status column shows whether each key is active or inactive.
  • Select Edit API key to change a key’s name, roles, or the merchant accounts it can access.
  • Select Deactivate to turn off a key without deleting it. A deactivated key can no longer authenticate. Select Activate to turn it back on.
  • Select Remove API key to delete a key. Removing a key is non-reversible, and any system using it can no longer authenticate.

​
Rotate an API key

To replace a key without downtime, run the old and new keys side by side while you switch over.
  1. Create an API key with the same permissions and merchant access as the key you’re replacing, and store the new private key securely.
  2. Update your systems to sign requests with the new private key. If your integration sets the key ID (kid) in the JWT header, copy the new key ID from the API Keys table and update that value too.
  3. Check that the Last used value of the old key stops changing. It can lag behind the most recent request by a few minutes.
  4. Select Deactivate on the old key. If anything still depends on it, those requests fail and you can select Activate to restore it while you fix them.
  5. Once nothing depends on the old key, select Remove API key to delete it.
If a key is compromised, deactivate it straight away rather than waiting for the switch-over to finish.
API key roles differ from user roles. User roles control access for people signing in to the dashboard, while API key permissions control access for server-side API calls.