openapi: 3.2.0 info: title: Gr4vy API Key Pairs API version: '1.0' description: 'Operations tagged API Key Pairs across 2 of this provider''s published API definitions: gr4vy-docs-v1-openapi.json, gr4vy-openapi.json. Each path carries the servers of the definition it was published in.' servers: - url: https://api.sandbox.{id}.gr4vy.app x-speakeasy-server-id: sandbox variables: id: default: example description: The subdomain for your Gr4vy instance. - url: https://api.{id}.gr4vy.app x-speakeasy-server-id: production variables: id: default: example description: The subdomain for your Gr4vy instance. tags: - name: API Key Pairs description: 'In Gr4vy, an API key pair is used to sign and validate JSON Web Tokens (JWT). JWTs are used as a HTTP `bearer` token to authenticate to the API. For more information please visit our in-depth authentication guide.' x-internal: true paths: /api-key-pairs: get: operationId: list-api-key-pairs summary: List API key description: Returns a list of active API key-pairs. tags: - API Key Pairs x-internal: true x-speakeasy-ignore: true parameters: - schema: type: integer default: 20 example: 1 minimum: 1 maximum: 100 format: int32 in: query name: limit description: Defines the maximum number of items to return for this request. - schema: type: string format: '' example: ZXhhbXBsZTE in: query name: cursor description: 'A cursor that identifies the page of results to return. This is used to paginate the results of this API. For the first page of results, this parameter can be left out. For additional pages, use the value returned by the API in the `next_cursor` field. Similarly the `previous_cursor` can be used to reverse backwards in the list.' responses: '200': description: Returns a list of active key pairs. content: application/json: schema: $ref: '#/components/schemas/APIKeyPairs' examples: A list of key pairs: value: items: - type: api-key-pair id: fe26475d-ec3e-4884-9553-f7356683f7f9 display_name: Storefront algorithm: ECDSA thumbprint: SopiN5XU0IWy8Xe9mwx1ICQbKh4-ydCDPx3LIyArkVI private_key: null creator: id: 5162f467-c5be-4673-8aae-6bbff795099b name: Demo User email_address: demo@gr4vy.com merchant_account: type: merchant-account id: default display_name: Default created_at: '2012-12-12T10:53:43+00:00' updated_at: '2012-12-12T10:53:43+00:00' created_at: '2012-12-12T10:53:43+00:00' updated_at: '2012-12-12T10:53:43+00:00' - type: api-key-pair id: c81bdcfd-00c2-4897-b220-06ff0e95685a display_name: Back Office algorithm: ECDSA thumbprint: Wy8Xe9mwx1ICQbKh4SopiN5XU0I-yArkVIydCDPx3LI private_key: null creator: id: 5162f467-c5be-4673-8aae-6bbff795099b name: Demo User email_address: demo@gr4vy.com merchant_account: type: merchant-account id: plantly-uk display_name: Plantly UK created_at: '2012-12-12T10:53:43+00:00' updated_at: '2012-12-12T10:53:43+00:00' created_at: '2012-12-12T10:53:12+00:00' updated_at: '2012-12-12T10:53:12+00:00' '401': description: Returns an error if no valid authentication was provided. content: application/json: schema: $ref: '#/components/schemas/Error401Unauthorized' security: - bearerAuth: [] post: operationId: new-api-key-pair summary: Create API key description: Creates a new API key-pair. tags: - API Key Pairs x-internal: true x-speakeasy-ignore: true requestBody: content: application/json: schema: $ref: '#/components/schemas/APIKeyPairCreate' examples: Create an API Key Pair: value: display_name: Back Office algorithm: ECDSA role_ids: - 8d3fe99b-1422-42e6-bbb3-932d95ae5f79 merchant_account_id: plantly-uk responses: '201': description: Returns a newly created key pair. content: application/json: schema: $ref: '#/components/schemas/APIKeyPair' examples: A newly created API key pair: value: type: api-key-pair id: fe26475d-ec3e-4884-9553-f7356683f7f9 display_name: Back Office algorithm: ECDSA thumbprint: SopiN5XU0IWy8Xe9mwx1ICQbKh4-ydCDPx3LIyArkVI private_key: REDACTED_PRIVATE_KEY_EXAMPLE creator: null merchant_account: type: merchant-account id: plantly-uk display_name: Plantly UK created_at: '2012-12-12T10:53:43+00:00' updated_at: '2012-12-12T10:53:43+00:00' created_at: '2012-12-12T10:53:43+00:00' updated_at: '2012-12-12T10:53:43+00:00' '401': description: Returns an error if no valid authentication was provided. content: application/json: schema: $ref: '#/components/schemas/Error401Unauthorized' security: - bearerAuth: [] servers: - url: https://api.sandbox.{id}.gr4vy.app x-speakeasy-server-id: sandbox variables: id: default: example description: The subdomain for your Gr4vy instance. - url: https://api.{id}.gr4vy.app x-speakeasy-server-id: production variables: id: default: example description: The subdomain for your Gr4vy instance. /api-key-pairs/{api_key_pair_id}: parameters: - schema: type: string example: gg9ILy name: api_key_pair_id in: path required: true description: The ID for the API key pair. put: operationId: update-api-key-pair summary: Update API key description: Updates an API key-pair. tags: - API Key Pairs x-internal: true x-speakeasy-ignore: true requestBody: content: application/json: schema: $ref: '#/components/schemas/APIKeyPairUpdate' examples: Update an API Key Pair: value: display_name: Back Office responses: '200': description: Returns the updated key pair. content: application/json: schema: $ref: '#/components/schemas/APIKeyPair' examples: An updated API Key Pair: value: type: api-key-pair id: fe26475d-ec3e-4884-9553-f7356683f7f9 display_name: Back Office algorithm: ECDSA thumbprint: SopiN5XU0IWy8Xe9mwx1ICQbKh4-ydCDPx3LIyArkVI private_key: null merchant_account: type: merchant-account id: plantly-uk display_name: Plantly UK created_at: '2012-12-12T10:53:43+00:00' updated_at: '2012-12-12T10:53:43+00:00' created_at: '2012-12-12T10:53:43+00:00' updated_at: '2012-12-15T10:53:43+00:00' '401': description: Returns an error if no valid authentication was provided. content: application/json: schema: $ref: '#/components/schemas/Error401Unauthorized' '404': description: Returns an error if the resource can not be found. content: application/json: schema: $ref: '#/components/schemas/Error404NotFound' security: - bearerAuth: [] delete: operationId: delete-api-key-pair summary: Delete API key description: Deletes an API key-pair. tags: - API Key Pairs x-internal: true x-speakeasy-ignore: true responses: '204': description: Returns an empty response. '401': description: Returns an error if no valid authentication was provided. content: application/json: schema: $ref: '#/components/schemas/Error401Unauthorized' '404': description: Returns an error if the resource can not be found. content: application/json: schema: $ref: '#/components/schemas/Error404NotFound' security: - bearerAuth: [] get: tags: - API Key Pairs summary: Get an API key pair description: Fetches an API key pair by its ID. operationId: get_api_key_pair security: - OAuth2PasswordBearer: - api-key-pairs.read parameters: - name: api_key_pair_id in: path required: true schema: type: string format: uuid description: The ID of the API key pair. examples: - fe26475d-ec3e-4884-9553-f7356683f7f9 title: Api Key Pair Id description: The ID of the API key pair. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/APIKeyPair_2' '400': description: The request was invalid. content: application/json: schema: $ref: '#/components/schemas/Error400' '401': description: The request was unauthorized. content: application/json: schema: $ref: '#/components/schemas/Error401' '403': description: The credentials were invalid or the caller did not have permission to act on the resource. content: application/json: schema: $ref: '#/components/schemas/Error403' '404': description: The resource was not found. content: application/json: schema: $ref: '#/components/schemas/Error404' '405': description: The request method was not allowed. content: application/json: schema: $ref: '#/components/schemas/Error405' '409': description: A duplicate record was found. content: application/json: schema: $ref: '#/components/schemas/Error409' '425': description: The request was too early. content: application/json: schema: $ref: '#/components/schemas/Error425' '429': description: Too many requests were made. content: application/json: schema: $ref: '#/components/schemas/Error429' '500': description: The server encountered an error. content: application/json: schema: $ref: '#/components/schemas/Error500' '502': description: The server encountered an error. content: application/json: schema: $ref: '#/components/schemas/Error502' '504': description: The server encountered an error. content: application/json: schema: $ref: '#/components/schemas/Error504' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' x-speakeasy-name-override: get x-speakeasy-group: api-key-pairs servers: - url: https://api.sandbox.{id}.gr4vy.app x-speakeasy-server-id: sandbox variables: id: default: example description: The subdomain for your Gr4vy instance. - url: https://api.{id}.gr4vy.app x-speakeasy-server-id: production variables: id: default: example description: The subdomain for your Gr4vy instance. components: schemas: APIKeyPair: title: API Key Pair type: object description: Details about an API key pair. x-internal: true x-tags: - API Key Pairs properties: type: type: string description: '`api-key-pair`.' example: api-key-pair enum: - api-key-pair id: type: string example: fe26475d-ec3e-4884-9553-f7356683f7f9 description: The unique Gr4vy ID for this key-pair. format: uuid display_name: type: string description: A name for this key-pair which is used in the Gr4vy admin panel to give the key-pair a human readable name. example: Sandbox minLength: 1 maxLength: 200 algorithm: type: string description: 'The algorithm to use for the API Key Pair. The recommended value is `ECDSA`. You should only use the `RSA` algorithm in environments that do not support `ECDSA`.' example: ECDSA enum: - ECDSA - RSA default: ECDSA thumbprint: type: string maxLength: 43 minLength: 43 pattern: ^[A-Za-z0-9-_]+$ description: A unique ID for this key-pair. This ID is the thumbprint of the key. example: SopiN5XU0IWy8Xe9mwx1ICQbKh4-ydCDPx3LIyArkVI private_key: type: - string - 'null' description: 'The private key for the key-pair. This is only returned after the key is initially requested. For subsequent API calls this value is `null`.' example: REDACTED_PRIVATE_KEY_EXAMPLE created_at: type: string format: date-time example: '2012-12-12T10:53:43+00:00' description: The date and time when this key pair was created. updated_at: type: string format: date-time example: '2012-12-12T10:53:43+00:00' description: The date and time when this key pair was last updated. creator: type: - object - 'null' description: The user who created the API Key Pair. properties: id: type: string format: uuid description: The ID of the user. example: 77a76f7e-d2de-4bbc-ada9-d6a0015e6bd5 name: type: string description: The name of the user. example: John L email_address: type: - string - 'null' description: The email address for this user. example: john@example.com merchant_account: $ref: '#/components/schemas/MerchantAccount' APIKeyPairs: title: A list of active API key pairs type: object description: A list of the currently active API key pairs. x-internal: true x-tags: - API Key Pairs properties: items: type: array items: $ref: '#/components/schemas/APIKeyPair' limit: type: integer description: 'The limit applied to request. This represents the number of items that are at maximum returned by this request.' format: int32 minimum: 1 maximum: 100 example: 1 default: 20 next_cursor: type: - string - 'null' description: 'The cursor that represents the next page of results. Use the `cursor` query parameter to fetch this page of items.' example: ZXhhbXBsZTE minLength: 1 maxLength: 1000 previous_cursor: type: - string - 'null' description: 'The cursor that represents the next page of results. Use the `cursor` query parameter to fetch this page of items.' example: null minLength: 1 maxLength: 1000 APIKeyPairUpdate: title: API key-pair (Update) type: object description: A request to update an API key-pair. x-tags: - API Key Pairs required: - display_name properties: display_name: type: string description: A name for this key-pair which is used in the Gr4vy admin panel to give the key-pair a human readable name. example: Sandbox minLength: 1 maxLength: 200 Error404NotFound: title: Not Found Error type: object description: Not Found Error (HTTP 404). x-tags: - Errors properties: type: type: string description: '`error`.' enum: - error example: error code: type: string description: The reason code for the error. example: not_found enum: - not_found - pending_creation status: type: integer description: '`404`.' example: 404 enum: - 404 message: type: string description: The human readable reason for the error. example: The resource could not be found details: type: array description: 'A list of detail objects that further clarify the reason for the error. Not every error supports more detail.' example: [] items: $ref: '#/components/schemas/ErrorDetail' ErrorDetail: title: Error details description: Additional detail about the part of a request body that caused an issue. type: object x-tags: - Errors properties: location: type: string example: body description: The location where the error caused an issue. enum: - query - body - path - header type: type: string example: value_error.missing description: A unique identifier for the type of error that occurred. pointer: type: string example: /payment_method/number description: 'The exact item for which the validation did not succeed. This is a JSON pointer for request bodies, while for query, path, and header parameters it is the name of the parameter.' message: type: string example: field required description: A human readable message for this error detail. APIKeyPairCreate: title: API key-pair (Create) type: object description: A request to create an API key-pair. x-tags: - API Key Pairs properties: display_name: type: string description: A name for this key-pair which is used in the Gr4vy admin panel to give the key-pair a human readable name. example: Sandbox minLength: 1 maxLength: 200 algorithm: type: string description: 'The algorithm to use for the API Key Pair. The recommended value is `ECDSA`. You should only use the `RSA` algorithm in environments that do not support `ECDSA`.' example: ECDSA enum: - ECDSA - RSA default: ECDSA role_ids: type: array minItems: 1 description: 'A list of role IDs that will be assigned to the API Key Pair being created. Only the "Administrator" and "Integration" roles are supported.' items: type: string format: uuid example: - 8d3fe99b-1422-42e6-bbb3-932d95ae5f79 merchant_account_id: type: - string - 'null' description: 'The optional ID of the merchant account this API Key Pair should be assigned to. Leave this unset to create an API key that works across all merchant accounts.' example: plantly-uk maxLength: 22 Error401Unauthorized: title: Unauthorized Error type: object description: Unauthorized Error (HTTP 401). x-tags: - Errors properties: type: type: string description: '`error`.' enum: - error example: error code: type: string description: '`unauthorized`.' example: unauthorized enum: - unauthorized status: type: integer description: '`401`.' example: 401 enum: - 401 message: type: string description: No valid API authentication found. example: No valid API authentication found enum: - No valid API authentication found details: type: array description: 'A list of detail objects that further clarify the reason for the error. Not every error supports more detail.' example: [] items: $ref: '#/components/schemas/ErrorDetail' MerchantAccount: title: Merchant Account type: object x-tags: - Merchant Account properties: type: type: string description: '`merchant-account`.' example: merchant-account enum: - merchant-account id: type: string description: The ID for this merchant account. example: plantly-uk display_name: type: string description: The display name of this merchant account. example: Plantly UK outbound_webhook_url: type: - string - 'null' format: uri description: The optional URL where webhooks will be received. example: https://www.example.com/webhook outbound_webhook_username: type: - string - 'null' description: 'The optional username to use when `outbound_webhook_url` is configured and requires basic authentication.' example: gr4vy outbound_webhook_password: type: - string - 'null' description: 'The optional password to use when `outbound_webhook_url` is configured and requires basic authentication. If the field is not `null`, the value is masked to avoid exposing sensitive information.' example: '********' visa_network_tokens_requestor_id: type: - string - 'null' description: Requestor ID provided for Visa after onboarding to use Network Tokens. example: e50fa0da-903d-4d54-aacc-4cac57d48df2 visa_network_tokens_app_id: type: - string - 'null' description: 'Application ID provided for Visa after onboarding to use Network Tokens.' example: e50fa0da-903d-4d54-aacc-4cac57d48df2 amex_network_tokens_requestor_id: type: - string - 'null' description: Requestor ID provided for Amex after onboarding to use Network Tokens. example: e50fa0da-903d-4d54-aacc-4cac57d48df2 amex_network_tokens_app_id: type: - string - 'null' description: Application ID provided for Amex after onboarding to use Network Tokens. example: e50fa0da-903d-4d54-aacc-4cac57d48df2 mastercard_network_tokens_requestor_id: type: - string - 'null' description: 'Requestor ID provided for Mastercard after onboarding to use Network Tokens.' example: e50fa0da-903d-4d54-aacc-4cac57d48df2 mastercard_network_tokens_app_id: type: - string - 'null' description: 'Application ID provided for Mastercard after onboarding to use Network Tokens.' example: e50fa0da-903d-4d54-aacc-4cac57d48df2 loon_client_key: type: - string - 'null' description: 'Client key provided by Pagos to authenticate to the Loon API. Loon is the Account Updater service used by Gr4vy.' example: 7DD771287D0024BA418F8F7ECC7DF1CD loon_secret_key: type: - string - 'null' description: 'Secret key provided by Pagos to authenticate to the Loon API. Loon is the Account Updater service used by Gr4vy. If the field is not `null`, the value is masked to avoid exposing sensitive information.' example: '********' loon_accepted_schemes: type: - array - 'null' items: type: string example: visa enum: - accel - amex - bancontact - carte-bancaire - cirrus - culiance - dankort - diners-club - discover - eftpos-australia - elo - hipercard - jcb - maestro - mastercard - mir - nyce - other - pulse - rupay - star - uatp - unionpay - visa - null description: 'Card schemes accepted when creating jobs using this set of Loon API keys. Loon is the Account Updater service used by Gr4vy.' example: - mastercard - visa account_updater_enabled: type: boolean example: true default: false description: 'Whether the Realtime Account Updater service is enabled for this merchant account. The Account Updater service is used to update card details when cards are lost, stolen or expired. * If the field is not set or if it''s set to `false`, the Account Updater service doesn''t get called if a payment fails with expired or invalid card details. * If the field is set to `true`, the service is called. Please note that for this to work the other `account_updater_*` fields must be set as well.' account_updater_request_encryption_key: type: - string - 'null' example: example-encryption-key description: 'The public key used to encrypt the request to the Realtime Account Updater service. The Account Updater service is used to update card details when cards are lost, stolen or expired. * If the field is not set or if it''s set to `null`, the Account Updater service doesn''t get called. * If the field is set, the other `account_updater_*` fields must be set as well.' account_updater_request_encryption_key_id: type: - string - 'null' example: example-encryption-key-id description: 'The public key ID used to encrypt the request to the Realtime Account Updater service. The Account Updater service is used to update card details when cards are lost, stolen or expired. * If the field is not set or if it''s set to `null`, the Account Updater service doesn''t get called. * If the field is set, the other `account_updater_*` fields must be set as well.' account_updater_response_decryption_key: type: - string - 'null' example: example-decryption-key description: 'The private key used to decrypt the response from the Realtime Account Updater service. The Account Updater service is used to update card details when cards are lost, stolen or expired. * If the field is not set or if it''s set to `null`, the Account Updater service doesn''t get called. * If the field is set, the other `account_updater_*` fields must be set as well.' account_updater_response_decryption_key_id: type: - string - 'null' example: example-decryption-key-id description: 'The private key ID used to decrypt the response from the Realtime Account Updater service. The Account Updater service is used to update card details when cards are lost, stolen or expired. * If the field is not set or if it''s set to `null`, the Account Updater service doesn''t get called. * If the field is set, the other `account_updater_*` fields must be set as well.' created_at: type: string description: The date and time when this merchant account was created. format: date-time example: '2022-02-01T14:20:00.000+00:00' updated_at: type: string description: The date and time when this merchant account was updated. format: date-time example: '2022-02-01T14:20:00.000+00:00' over_capture_amount: type: - number - 'null' example: 1000 minimum: 1 maximum: 99999999 description: 'The maximum monetary amount allowed for over-capture, in the smallest currency unit, for example `1299` cents to allow for an over-capture of `$12.99`.' over_capture_percentage: type: - number - 'null' example: 20 minimum: 1 maximum: 99999999 description: 'The maximum percentage allowed for over-capture, for example `25` to allow for an over-capture of 25% of the original transaction amount.' Error401: properties: type: type: string const: error title: Type description: Always `error`. default: error examples: - error code: type: string title: Code description: Always `unauthorized` default: unauthorized examples: - unauthorized status: type: integer title: Status description: Always `401`. default: 401 examples: - 401 message: type: string title: Message description: A human readable message that provides more context to the error. default: No valid API authentication found examples: - No valid API authentication found details: items: $ref: '#/components/schemas/ErrorDetail_2' type: array title: Details description: A list of details that further ellaborate on the error. default: [] additionalProperties: false type: object title: Error401 Error404: properties: type: type: string const: error title: Type description: Always `error`. default: error examples: - error code: type: string title: Code description: Always `not_found` default: not_found examples: - not_found status: type: integer title: Status description: Always `404`. default: 404 examples: - 404 message: type: string title: Message description: A human readable message that provides more context to the error. default: The resource could not be found examples: - The resource could not be found details: items: $ref: '#/components/schemas/ErrorDetail_2' type: array title: Details description: A list of details that further ellaborate on the error. default: [] additionalProperties: false type: object title: Error404 ErrorLocation: type: string enum: - query - body - path - header - unknown title: ErrorLocation Error425: properties: type: type: string const: error title: Type description: Always `error`. default: error examples: - error code: type: string title: Code description: Always `too_early` default: too_early examples: - too_early status: type: integer title: Status description: Always `425`. default: 425 examples: - 425 message: type: string title: Message description: A human readable message that provides more context to the error. default: Generic error examples: - Request failed validation details: items: $ref: '#/components/schemas/ErrorDetail_2' type: array title: Details description: A list of details that further ellaborate on the error. default: [] additionalProperties: false type: object title: Error425 Collection_APIKeyPair_: properties: items: items: $ref: '#/components/schemas/APIKeyPair_2' type: array title: Items description: A list of items returned for this request. limit: type: integer maximum: 100.0 minimum: 1.0 title: Limit description: The number of items for this page. default: 20 examples: - 20 next_cursor: anyOf: - type: string maxLength: 1000 minLength: 1 - type: 'null' title: Next Cursor description: The cursor pointing at the next page of items. examples: - ZXhhbXBsZTE previous_cursor: anyOf: - type: string maxLength: 1000 minLength: 1 - type: 'null' title: Previous Cursor description: The cursor pointing at the previous page of items. examples: - Xkjss7asS additionalProperties: false type: object required: - items title: Collection[APIKeyPair] RoleAssigneeType: type: string enum: - user - api-key-pair title: RoleAssigneeType api__routers__api_key_pairs__schemas__Creator: properties: id: type: string format: uuid title: Id description: The ID of the user or API key pair that created the API key pair. examples: - fe26475d-ec3e-4884-9553-f7356683f7f9 name: type: string title: Name description: The name of the user or API key pair that created the API key pair. examples: - John Doe email_address: anyOf: - type: string - type: 'null' title: Email Address description: The email address of the user that created the API key pair, when it was created by a dashboard user. examples: - john.doe@example.com thumbprint: anyOf: - type: string - type: 'null' title: Thumbprint description: The thumbprint of the API key pair that created the API key pair, when it was created by another API key. examples: - 6zsbrjs0Cp4M4Ebz8sfHqUKGiG9Sd0lF2sfKp5-w-nk additionalProperties: false type: object required: - id - name title: Creator HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError ErrorDetail_2: properties: location: $ref: '#/components/schemas/ErrorLocation' description: The part of the request where the property can be found that caused the error. examples: - body pointer: anyOf: - type: string format: json-pointer - type: string title: Pointer description: A JSON pointer for the particular property that caused the error. examples: - /currency message: type: string title: Message description: A human-readdable explanation of the error. examples: - 'Unknown ISO 4217 currency code: USX' type: type: string title: Type description: The type of error that was raised for this property. examples: - value_error additionalProperties: false type: object required: - location - pointer - message - type title: ErrorDetail Error405: properties: type: type: string const: error title: Type description: Always `error`. default: error examples: - error code: type: string title: Code description: Always `method_not_allowed` default: method_not_allowed examples: - method_not_allowed status: type: integer title: Status description: Always `405`. default: 405 examples: - 405 message: type: string title: Message description: A human readable message that provides more context to the error. default: Method Not Allowed examples: - Method Not Allowed details: items: $ref: '#/components/schemas/ErrorDetail_2' type: array title: Details description: A list of details that further ellaborate on the error. default: [] additionalProperties: false type: object title: Error405 Error429: properties: type: type: string const: error title: Type description: Always `error`. default: error examples: - error code: type: string title: Code description: Always `too_many_requests` default: too_many_requests examples: - too_many_requests status: type: integer title: Status description: Always `429`. default: 429 examples: - 429 message: type: string title: Message description: A human readable message that provides more context to the error. default: Generic error examples: - Request failed validation details: items: $ref: '#/components/schemas/ErrorDetail_2' type: array title: Details description: A list of details that further ellaborate on the error. default: [] additionalProperties: false type: object title: Error429 Role: properties: type: type: string const: role title: Type description: Always `role`. default: role examples: - role id: type: string format: uuid title: Id description: The unique ID for the role. examples: - fe26475d-ec3e-4884-9553-f7356683f7f9 name: type: string title: Name description: The human-readable name of the role. examples: - Administrator slug: type: string title: Slug description: The unique, human-readable identifier for the role. examples: - administrator description: type: string title: Description description: A description of the access this role grants. examples: - Full read and write access. permissions: $ref: '#/components/schemas/PermissionSet' description: The permissions granted by this role. assignable_to: items: $ref: '#/components/schemas/RoleAssigneeType' type: array title: Assignable To description: The types of resource this role can be assigned to. applies_to: items: type: string type: array title: Applies To description: The slugs of the roles this role is an add-on of. Empty when this role is not an add-on. is_standalone_assignable: type: boolean title: Is Standalone Assignable description: Whether this role can be assigned on its own, without being combined with another role. additionalProperties: false type: object required: - id - name - slug - description - permissions - assignable_to - applies_to - is_standalone_assignable title: Role APIKeyPair_2: properties: type: type: string const: api-key-pair title: Type description: The type of this resource. default: api-key-pair id: type: string format: uuid title: Id description: The ID for the API key pair. examples: - fe26475d-ec3e-4884-9553-f7356683f7f9 thumbprint: type: string title: Thumbprint description: The unique thumbprint that identifies the API key pair. examples: - 6zsbrjs0Cp4M4Ebz8sfHqUKGiG9Sd0lF2sfKp5-w-nk display_name: type: string maxLength: 200 minLength: 1 title: Display Name description: The display name for the API key pair. examples: - Production key algorithm: $ref: '#/components/schemas/CertificateAlgorithm' description: The algorithm used to generate the API key pair. examples: - ECDSA active: type: boolean title: Active description: Whether the API key pair is active and can be used to authenticate. examples: - true private_key: anyOf: - type: string - type: 'null' title: Private Key description: 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. created_at: type: string format: date-time title: Created At description: The date and time when this API key pair was created. examples: - '2013-07-16T19:23:00.000+00:00' updated_at: type: string format: date-time title: Updated At description: The date and time when this API key pair was last updated. examples: - '2013-07-16T19:23:00.000+00:00' last_used_at: anyOf: - type: string format: date-time - type: 'null' title: Last Used At description: The date and time when this API key pair was last used to authenticate, or `null` if it has never been used. examples: - '2013-07-16T19:23:00.000+00:00' creator: anyOf: - $ref: '#/components/schemas/api__routers__api_key_pairs__schemas__Creator' - type: 'null' description: The user or API key pair that created this API key pair. merchant_accounts: items: $ref: '#/components/schemas/MerchantAccountSummary' type: array title: Merchant Accounts description: The merchant accounts this API key pair has access to. An empty list means it has access to all merchant accounts. roles: items: $ref: '#/components/schemas/Role' type: array title: Roles description: The roles assigned to this API key pair. additionalProperties: false type: object required: - id - thumbprint - display_name - algorithm - active - created_at - updated_at title: APIKeyPair Error500: properties: type: type: string const: error title: Type description: Always `error`. default: error examples: - error code: type: string title: Code description: Always `server_error` default: server_error examples: - server_error status: type: integer title: Status description: Always `500`. default: 500 examples: - 500 message: type: string title: Message description: A human readable message that provides more context to the error. default: Request could not be processed examples: - Request could not be processed details: items: $ref: '#/components/schemas/ErrorDetail_2' type: array title: Details description: A list of details that further ellaborate on the error. default: [] additionalProperties: false type: object title: Error500 Error504: properties: type: type: string const: error title: Type description: Always `error`. default: error examples: - error code: type: string title: Code description: Always `gateway_timeout` default: gateway_timeout examples: - gateway_timeout status: type: integer title: Status default: 504 message: type: string title: Message description: A human readable message that provides more context to the error. default: Request could not be processed examples: - Request could not be processed details: items: $ref: '#/components/schemas/ErrorDetail_2' type: array title: Details description: A list of details that further ellaborate on the error. default: [] additionalProperties: false type: object title: Error504 APIKeyPairUpdate_2: properties: display_name: anyOf: - type: string maxLength: 200 minLength: 1 - type: 'null' title: Display Name description: The display name for the API key pair. examples: - Production key active: anyOf: - type: boolean - type: 'null' title: Active description: Whether the API key pair is active and can be used to authenticate. examples: - true role_ids: anyOf: - items: type: string format: uuid type: array minItems: 1 description: The IDs of the roles to assign to the API key pair, replacing the roles it currently has. The caller can only assign roles whose scopes are a subset of its own. examples: - - 8f4b8c1a-1b2c-4d3e-9f5a-6b7c8d9e0f1a - 2c9a7f3d-4e5b-4a6c-8d7e-9f0a1b2c3d4e - type: 'null' title: Role Ids merchant_account_ids: anyOf: - items: type: string type: array - type: 'null' title: Merchant Account Ids description: The IDs of the merchant accounts to associate with the API key pair. The caller can only assign merchant accounts it has access to. examples: - - merchant-12345 additionalProperties: false type: object title: APIKeyPairUpdate Error400: properties: type: type: string const: error title: Type description: Always `error`. default: error examples: - error code: type: string title: Code description: Always `bad_request` default: bad_request examples: - bad_request status: type: integer title: Status description: Always `400`. default: 400 examples: - 400 message: type: string title: Message description: A human readable message that provides more context to the error. default: Generic error examples: - Request failed validation details: items: $ref: '#/components/schemas/ErrorDetail_2' type: array title: Details description: A list of details that further ellaborate on the error. default: [] additionalProperties: false type: object title: Error400 APIKeyPairCreate_2: properties: display_name: type: string maxLength: 200 minLength: 1 title: Display Name description: The display name for the API key pair. examples: - Production key algorithm: $ref: '#/components/schemas/CertificateAlgorithm' description: The algorithm to use to generate the API key pair. default: ECDSA examples: - ECDSA active: type: boolean title: Active description: Whether the API key pair should be active and usable once created. default: true examples: - true role_ids: items: type: string format: uuid type: array minItems: 1 title: Role Ids description: The IDs of the roles to assign to the API key pair. The caller can only assign roles whose scopes are a subset of its own. examples: - - 8f4b8c1a-1b2c-4d3e-9f5a-6b7c8d9e0f1a - 2c9a7f3d-4e5b-4a6c-8d7e-9f0a1b2c3d4e merchant_account_ids: items: type: string type: array title: Merchant Account Ids description: 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. examples: - - merchant-12345 public_key: anyOf: - type: string - type: 'null' title: Public Key description: 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. examples: - '-----BEGIN PUBLIC KEY----- MIGbMBAGByqGSM49AgEGBSuBBAAjA4GGAAQB... -----END PUBLIC KEY-----' additionalProperties: false type: object required: - display_name - role_ids title: APIKeyPairCreate Error502: properties: type: type: string const: error title: Type description: Always `error`. default: error examples: - error code: type: string title: Code description: Always `bad_gateway` default: bad_gateway examples: - bad_gateway status: type: integer title: Status description: Always `502`. default: 502 examples: - 502 message: type: string title: Message description: A human readable message that provides more context to the error. default: Request could not be processed examples: - Request could not be processed details: items: $ref: '#/components/schemas/ErrorDetail_2' type: array title: Details description: A list of details that further ellaborate on the error. default: [] additionalProperties: false type: object title: Error502 ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError PermissionSet: properties: allow: items: type: string type: array title: Allow description: The scopes granted by this role. examples: - - transactions.read - reports.read additionalProperties: false type: object required: - allow title: PermissionSet description: The permissions granted by a role. CertificateAlgorithm: type: string enum: - ECDSA - RSA title: CertificateAlgorithm Error409: properties: type: type: string const: error title: Type description: Always `error`. default: error examples: - error code: type: string title: Code description: Always `duplicate_record` default: duplicate_record examples: - duplicate_record status: type: integer title: Status description: Always `409`. default: 409 examples: - 409 message: type: string title: Message description: A human readable message that provides more context to the error. default: Generic error examples: - Request failed validation details: items: $ref: '#/components/schemas/ErrorDetail_2' type: array title: Details description: A list of details that further ellaborate on the error. default: [] resource_id: anyOf: - type: string - type: 'null' title: Resource Id description: The ID of the conflicting resource. examples: - cdc70639-cb9c-4222-a73f-b8ce39f7821b additionalProperties: false type: object title: Error409 Error403: properties: type: type: string const: error title: Type description: Always `error`. default: error examples: - error code: type: string title: Code description: Always `forbidden` default: forbidden examples: - forbidden status: type: integer title: Status description: Always `403`. default: 403 examples: - 403 message: type: string title: Message description: A human readable message that provides more context to the error. default: Generic error examples: - Request failed validation details: items: $ref: '#/components/schemas/ErrorDetail_2' type: array title: Details description: A list of details that further ellaborate on the error. default: [] additionalProperties: false type: object title: Error403 MerchantAccountSummary: properties: type: type: string const: merchant-account title: Type default: merchant-account id: type: string title: Id display_name: type: string title: Display Name created_at: type: string format: date-time title: Created At updated_at: type: string format: date-time title: Updated At over_capture_amount: anyOf: - type: integer - type: 'null' title: Over Capture Amount over_capture_percentage: anyOf: - type: integer - type: 'null' title: Over Capture Percentage additionalProperties: false type: object required: - id - display_name - created_at - updated_at title: MerchantAccountSummary securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT OAuth2PasswordBearer: type: oauth2 flows: password: scopes: embed: Shorthand for all gr4vy embed related scopes sessions.refresh: Refresh access-token anti-fraud-service-definitions.read: Read Anti Fraud Service Definitions anti-fraud-services.read: Read Anti Fraud Services api-key-pairs.read: Read API Key Pairs api-logs.read: Read API Logs apple-pay-certificates.read: Read Apple Pay Certificates audit-logs.read: Read Audit Logs bin-checker.read: Read BIN Checker buyers.read: Read Buyers buyers.billing-details.read: Read Billing Details card-scheme-definitions.read: Read Card Scheme Definitions checkout-sessions.read: Read Checkout Sessions connections.read: Read Connections digital-wallets.read: Read Digital Wallets flows.read: Read Flows gift-card-service-definitions.read: Read Gift Card Service Definitions gift-card-services.read: Read Gift Card Services gift-cards.read: Read Gift Cards merchant-accounts.read: Read Merchant Accounts payment-links.read: Read Payment Links payment-method-definitions.read: Read Payment Method Definitions payment-methods.read: Read Payment Methods payment-options.read: Read Payment Options payment-service-definitions.read: Read Payment Service Definitions payment-services.read: Read Payment Service payouts.read: Read Payouts reports.read: Read Reports roles.read: Read Roles three-ds-scenarios.read: Read 3DS Scenarios transactions.read: Read Transactions users.me.read: Read User Profile vault-forward.read: Read Vault Forward vault-forward-authentications.read: Read Vault Forward Authentications vault-forward-configs.read: Read Vault Forward Configurations vault-forward-definitions.read: Read Vault Forward Definitions webhook-subscriptions.read: Read Webhook Subscriptions business-contexts.read: Read Business Contexts health-dashboard.read: Read Health Dashboard metrics-explorer.read: Read Metrics Explorer monitoring.read: Read Monitoring reset.read: Read Reset sessions.read: Read Sessions users.read: Read Users anti-fraud-service-definitions.write: Write Anti Fraud Service Definitions anti-fraud-services.write: Write Anti Fraud Services api-key-pairs.write: Write API Key Pairs api-logs.write: Write API Logs apple-pay-certificates.write: Write Apple Pay Certificates audit-logs.write: Write Audit Logs bin-checker.write: Write BIN Checker buyers.write: Write Buyers buyers.billing-details.write: Write Billing Details card-scheme-definitions.write: Write Card Scheme Definitions checkout-sessions.write: Write Checkout Sessions connections.write: Write Connections digital-wallets.write: Write Digital Wallets flows.write: Write Flows gift-card-service-definitions.write: Write Gift Card Service Definitions gift-card-services.write: Write Gift Card Services gift-cards.write: Write Gift Cards merchant-accounts.write: Write Merchant Accounts payment-links.write: Write Payment Links payment-method-definitions.write: Write Payment Method Definitions payment-methods.write: Write Payment Methods payment-options.write: Write Payment Options payment-service-definitions.write: Write Payment Service Definitions payment-services.write: Write Payment Service payouts.write: Write Payouts reports.write: Write Reports roles.write: Write Roles three-ds-scenarios.write: Write 3DS Scenarios transactions.write: Write Transactions users.me.write: Write User Profile vault-forward.write: Write Vault Forward vault-forward-authentications.write: Write Vault Forward Authentications vault-forward-configs.write: Write Vault Forward Configurations vault-forward-definitions.write: Write Vault Forward Definitions webhook-subscriptions.write: Write Webhook Subscriptions business-contexts.write: Write Business Contexts health-dashboard.write: Write Health Dashboard metrics-explorer.write: Write Metrics Explorer monitoring.write: Write Monitoring reset.write: Write Reset sessions.write: Write Sessions users.write: Write Users tokenUrl: auth/token x-refined-from: - gr4vy-docs-v1-openapi.json - gr4vy-openapi.json