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 a sandbox account with Griffin and try out our API in sandbox mode. For now, if you want to go live, you'll need to contact us.
Creating an API key
- Create a sandbox account at https://app.griffin.com/register
- Click Developers to create an API key.
- Give your API key a memorable name and store it somewhere safe.
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
- you can replace this with your own 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
.
Navigating the API
The primary method of navigating our API is following URLs you find in responses. While exploring, you should never need to construct URLs yourself using IDs: instead, you can make a single initial request and follow links from one resource to another.
If you already know the ID of a resource, you can use our API Reference to construct a direct URL to it.
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.
Example
In this example, you will be able to walk the API from the index
resource to querying the transactions for a bank account.
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"
}
Follow the api-key-url
to discover your organization-url
. This organization-url
is unique to you and most API resources, e.g. bank accounts and legal persons will be a child of it.
curl "https://api.griffin.com/v0/api-keys/ak.0j3-IZIOSFytCD-9SqMdPw" -H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY"
{
"api-key-live?": false,
"api-key-name": "foo",
"api-key-url": "/v0/api-keys/ak.0j3-IZIOSFytCD-9SqMdPw",
"organization-url": "/v0/organizations/og.o1rsp7efTN6CpMRybuu4OA",
"user-url": "/v0/users/ur.Etc0gzcURoSjMOAOZrnjmg"
}
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
in the data structure above, 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, where there is a single account defined:
{
"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 a 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.
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 |
You’ll be able to send another request, once you receive a response to any of your active requests.
Exceeding the concurrency limit
When the limit is exceeded the API will respond with a HTTP code 429 - Too Many Requests.
HTTP/1.1 429 Too Many Requests
Date: Wed, 02 May 2024 09:00:00 GMT
Content-Length: 0
You will need to consider these limits as part of your implementation ensuring you are tracking active requests, or designing your integration so that requests to our API 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.
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.