Skip to main content
POST
/
api-key-pairs
C#
using Gr4vy;
using Gr4vy.Models.Components;
using System.Collections.Generic;

var sdk = new Gr4vySDK(
    id: "example",
    server: SDKConfig.Server.Sandbox,
    bearerAuthSource: Auth.WithToken(privateKey),
    merchantAccountId: "default"
);

APIKeyPairCreate req = new APIKeyPairCreate() {
    DisplayName = "Production key",
    RoleIds = new List<string>() {
        "8f4b8c1a-1b2c-4d3e-9f5a-6b7c8d9e0f1a",
    },
};

var res = await sdk.ApiKeyPairs.CreateAsync(req);

// handle response
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "thumbprint": "<string>",
  "display_name": "<string>",
  "active": true,
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "type": "api-key-pair",
  "private_key": "<string>",
  "creator": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "email_address": "john.doe@example.com",
    "thumbprint": "6zsbrjs0Cp4M4Ebz8sfHqUKGiG9Sd0lF2sfKp5-w-nk"
  },
  "merchant_accounts": [
    {
      "id": "<string>",
      "display_name": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "type": "merchant-account",
      "over_capture_amount": 123,
      "over_capture_percentage": 123
    }
  ],
  "roles": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "description": "<string>",
      "permissions": {
        "allow": [
          "<string>"
        ]
      },
      "type": "role"
    }
  ]
}
This endpoint requires the api-key-pairs.write scope.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
display_name
string
required

The display name for the API key pair.

Required string length: 1 - 200
Example:

"Production key"

role_ids
string<uuid>[]
required

The ID of the role to assign to the API key pair. Exactly one role is supported. The caller can only assign a role whose scopes are a subset of its own.

Required array length: 1 element
Example:
["8f4b8c1a-1b2c-4d3e-9f5a-6b7c8d9e0f1a"]
algorithm
enum<string>
default:ECDSA

The algorithm to use to generate the API key pair.

Available options:
ECDSA,
RSA
Example:

"ECDSA"

active
boolean
default:true

Whether the API key pair should be active and usable once created.

Example:

true

merchant_account_ids
string[]

The IDs of the merchant accounts to associate with the API key pair. An empty list grants access to all merchant accounts. The caller can only assign merchant accounts it has access to.

Example:
["merchant-12345"]
public_key
string | null

A PEM-encoded ECDSA P-521 (ES512) public key. Provide this to register your own key pair (bring your own key); If omitted, Gr4vy will generate the key pair and return the private key.

Example:

"-----BEGIN PUBLIC KEY-----\nMIGbMBAGByqGSM49AgEGBSuBBAAjA4GGAAQB...\n-----END PUBLIC KEY-----"

Response

Successful Response

id
string<uuid>
required

The ID for the API key pair.

Example:

"fe26475d-ec3e-4884-9553-f7356683f7f9"

thumbprint
string
required

The unique thumbprint that identifies the API key pair.

Example:

"6zsbrjs0Cp4M4Ebz8sfHqUKGiG9Sd0lF2sfKp5-w-nk"

display_name
string
required

The display name for the API key pair.

Required string length: 1 - 200
Example:

"Production key"

algorithm
enum<string>
required

The algorithm used to generate the API key pair.

Available options:
ECDSA,
RSA
Example:

"ECDSA"

active
boolean
required

Whether the API key pair is active and can be used to authenticate.

Example:

true

created_at
string<date-time>
required

The date and time when this API key pair was created.

Example:

"2013-07-16T19:23:00.000+00:00"

updated_at
string<date-time>
required

The date and time when this API key pair was last updated.

Example:

"2013-07-16T19:23:00.000+00:00"

type
string
default:api-key-pair

The type of this resource.

Allowed value: "api-key-pair"
private_key
string | null

The PEM-encoded private key. Only returned once, in the response to creating the API key pair, and only when Gr4vy generated the key pair. Store it securely, as it cannot be retrieved later.

creator
Creator · object | null

The user or API key pair that created this API key pair.

merchant_accounts
MerchantAccountSummary · object[]

The merchant accounts this API key pair has access to. An empty list means it has access to all merchant accounts.

roles
Role · object[]

The roles assigned to this API key pair.