Skip to main content
API key pairs can be provisioned and managed over the API, in addition to the dashboard. This lets you automate key provisioning at scale, such as issuing a key for each merchant during an independent sales organization (ISO) onboarding flow.

​
The Key Manager role

Managing API keys over the API requires the Key Manager role. This role is scoped strictly to the API key lifecycle through the api-key-pairs.read and api-key-pairs.write permissions. It grants no access to payments or back-office data. The Administrator role can also manage keys, but Key Manager keeps key management separate from payments and configuration access. The Key Manager role is not granted by default and is assignable only to an API key. Assign it from the dashboard to the API key that provisions keys.
The Administrator and Key Manager roles can only be assigned by a dashboard user. An API key cannot create or update another key with either role, even when it holds the Key Manager role itself.

​
Create a key

Create a key pair with a POST to the /api-key-pairs endpoint. A key requires a display_name and exactly one role in role_ids. 
var apiKeyPair = await client.ApiKeyPairs.CreateAsync(
    new APIKeyPairCreate()
    {
        DisplayName = "Onboarding service",
        RoleIds = new List<string>() { "<role-id>" },
        MerchantAccountIds = new List<string>() { "default", "acme-au" },
    }
);
By default, Gr4vy generates the key pair and returns the private_key once, in the response to this request. Store it securely, as it cannot be retrieved again. See the Create API key reference for more detail on this endpoint.

​
Provide your own public key

Rather than have Gr4vy generate the key pair, you can supply your own public key in the public_key field on create. When you do, Gr4vy stores the public key and does not generate or return a private key, so the private key never leaves your systems. The public key must be a PEM-encoded ECDSA key on the P-521 (ES512) curve. RSA keys are not accepted. Set algorithm to match, and note that the public key is immutable for the life of the key. 
var apiKeyPair = await client.ApiKeyPairs.CreateAsync(
    new APIKeyPairCreate()
    {
        DisplayName = "Onboarding service",
        RoleIds = new List<string>() { "<role-id>" },
        Algorithm = "ES512",
        PublicKey =
            "-----BEGIN PUBLIC KEY-----\n<pem-encoded-es512-public-key>\n-----END PUBLIC KEY-----",
    }
);

​
Issue a key for multiple merchant accounts

A single key can be scoped to more than one merchant account by passing an array of merchant account IDs in merchant_account_ids. This is useful when one ISO or brand groups several merchant accounts. The list is editable after creation. Add or remove merchant accounts with a PUT to the key, without regenerating the key or its private key. To grant a key access to all merchant accounts, pass an empty list or omit merchant_account_ids. This is only allowed when the caller can already access all merchant accounts.

​
Turn a key on or off

Each key has an active field that you can update over the API and in the dashboard. Set active to false to turn off a key. A request authenticated with an off key is rejected with a 401 Unauthorized response, which lets you revoke access immediately without deleting the key. 
var apiKeyPair = await client.ApiKeyPairs.UpdateAsync(
    apiKeyPairId: "<api-key-pair-id>",
    apiKeyPairUpdate: new APIKeyPairUpdate()
    {
        Active = false,
    }
);

​
Lifecycle webhooks

Gr4vy emits webhook events as keys change, so you can keep an audit trail of provisioning:
  • api-key-pair.created
  • api-key-pair.updated
  • api-key-pair.deleted
The api-key-pair.updated event covers all changes to an existing key, including enabling or disabling it and editing its merchant accounts. Subscribe to these events through the existing webhook subscription mechanism.