Get started with the API

Welcome to the Griffin API! This guide will take you through creating an API key and introduce some concepts you need to get started.

Anyone can create an account with Griffin and start experimenting with our API in sandbox. For now, if you want to go live, you'll need to contact us at support@griffin.com.

Creating an API key

Create an account or log in to the Griffin app.
Navigate to Settings > API keys.
Click Create key, and give your API key a memorable name.
Copy the displayed key and store it somewhere safe.

caution

The API key will only be shown once. If you lose it, you'll need to log in, delete it and create a new one. There is currently no limit on the number of API keys you can create.

Throughout our docs, the API key will be referred to as $GRIFFIN_API_KEY.

Check that you can connect to the API by calling the index resource. The API key is provided in the Authorization header.

curl "https://api.griffin.com/v0/index" -H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY"

If successful, you will be returned something like this:

{
  "organizations-url": "/v0/organizations",
  "api-key-url": "/v0/api-keys/ak.0j3-IZIOSFytCD-9SqMdPw",
  "organization-url": "/v0/organizations/og.2To90xd1QV2IdWh1Ay8Epw",
  "roles-url": "/v0/roles",
  "users-url": "/v0/users"
}

Standard HTTP headers

We have three standard headers relevant to most requests:

Authorization: GriffinAPIKey $GRIFFIN_API_KEY
Content-Type: application/json
Accept: application/json

Authorization

All API requests require the Authorization header. The value of the header is always GriffinAPIKey plus your API key. You don't need to encode the API key in any way; just send it as plain text.

We do not support Basic as an authorization method in our API.

Accept

The Accept header determines what format you receive the response in. We support only application/json at present, which is the default.

Content-Type

When a request has a body, you must provide the Content-Type header specifying its media type. At present, we only support application/json.

Exploring your organization

The organization resource represents your company and acts as a container for the majority of other API resources, such as legal persons and bank accounts.

When you register for an account with Griffin, a new organization is created alongside your user account (unless you have accepted an invitation to join an existing organization). Your user account is associated with an organization via a membership.

Once you have your API key, you can request the index resource:

curl "https://api.griffin.com/v0/index" -H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY"

The response will include a set of URLs you can use to begin navigating the API:

{
  "api-key-url": "/v0/api-keys/ak.0j3-IZIOSFytCD-9SqMdPw",
  "organization-url": "/v0/organizations/og.2To90xd1QV2IdWh1Ay8Epw",
  "organizations-url": "/v0/organizations",
  "roles-url": "/v0/roles",
  "users-url": "/v0/users"
}

Requesting organization-url returns a list of related resource URLs:

curl "https://api.griffin.com/v0/organizations/og.o1rsp7efTN6CpMRybuu4OA" -H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY"

{
    "display-name": "Acme Ltd",
    "organization-api-keys-url": "/v0/organizations/og.o1rsp7efTN6CpMRybuu4OA/api-keys",
    "organization-bank-accounts-url": "/v0/organizations/og.o1rsp7efTN6CpMRybuu4OA/bank/accounts",
    "organization-invitations-url": "/v0/organizations/og.o1rsp7efTN6CpMRybuu4OA/invitations",
    "organization-legal-persons-url": "/v0/organizations/og.o1rsp7efTN6CpMRybuu4OA/legal-persons",
    "organization-memberships-url": "/v0/organizations/og.o1rsp7efTN6CpMRybuu4OA/memberships",
    "organization-mode": "test-mode",
    "organization-url": "/v0/organizations/og.o1rsp7efTN6CpMRybuu4OA",
    "own-legal-person-url": "/v0/legal-persons/lp.Yvzfs9oJUeKsqHmu3-Us_g"
}

If you want to see a list of bank accounts, look up organization-bank-accounts-url and request the URL. In the example, the URL is /v0/organizations/og.o1rsp7efTN6CpMRybuu4OA/bank/accounts: appending that to https://api.griffin.com will return the list of bank accounts.

curl "https://api.griffin.com/v0/organizations/og.o1rsp7efTN6CpMRybuu4OA/bank/accounts" -H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY"

The response will look like this (if your organization only has one bank account):

{
  "accounts": [
    {
      "account-url": "/v0/bank/accounts/ac.yGeZn1SrXX6z4wsylawrHA",
      "display-name": "My Account",
      "beneficiary-url": "/v0/legal-persons/lp.aDBVscJYVya5eU2V6PqkmQ",
      "account-balance": {
        "currency": "GBP",
        "value": "100.00"
      },
      "account-transactions-url": "/v0/bank/accounts/ac.yGeZn1SrXX6z4wsylawrHA/transactions",
      "bank-product-type": "operational-account",
      "owner-url": "/v0/legal-persons/lp.aDBVscJYVya5eU2V6PqkmQ",
      "controller-url": "/v0/legal-persons/lp.aDBVsDJYXyaAeU2V6PqkmQ"
    }
  ]
}

To see a list of transactions for the bank account, fetch the URL found under account-transactions-url.

In this way, you can navigate the API in its entirety, starting with only your API key. If you already know the ID of a specific resource, you can use our API Reference to construct a direct URL to it.

info

We have a Postman collection for the Griffin API. Set your API key as an environment variable named griffin-api-key within your Postman workspace to get started.

caution

Message signatures should not be enforced in your organization when using our Postman collection.

Request limits

A concurrency limit is a limit on the number of in-flight requests at any time. Different concurrency limits apply to different resources:

Request type	Endpoint	Concurrency limit
Outbound payments submitted from the same bank account. This concurrency limit is specific to each bank account; submissions across different bank accounts are not affected.	Submit payment	3
All other requests made to our API		50

When the limit is exceeded. the API will respond with the HTTP code 429 - Too Many Requests. Once you receive a response to any of your active requests, you will be able to send another request.

HTTP/1.1 429 Too Many Requests
Date: Wed, 02 May 2024 09:00:00 GMT
Content-Length: 0

You will need to consider request limits as part of your integration. You should track active requests, or design your integration so that requests are performed via a finite pool of threads or workers.

You will also need to handle 429 responses appropriately, using a backoff and retrying the request.

API versions

The Griffin API is versioned via a prefix in the URL. The current version is v0.

An example endpoint is: https://api.griffin.com/v0/index.

We provide a backwards compatibility guarantee:

We will not change the meaning of a key in a request or a response.
We will not remove required keys from a response.
We may stop requiring a key in a request.
We may add new optional keys to a request.
We may add new keys to a response.

info

As we add features, we will inevitably add keys. Unknown keys are safe to accept and ignore while the version number remains the same.

We will not break your integration with a particular version for as long as we support that version.

If we release a new version, you will have 12 months to upgrade to it. That said, our goal is to avoid releasing new versions. We don’t want to end up supporting multiple versions and we don’t want to force you to change working code. The Griffin platform is intended to be stable over time.

Creating an API key​

Standard HTTP headers​

Authorization​

Accept​

Content-Type​

Exploring your organization​

Request limits​

API versions​