Skip to main content

API security

Our platform supports two levels of API authentication.

  • API keys: mandatory for all organizations.
  • Message signatures: will be mandatory for all live organizations in the near future, will always be optional for sandbox organizations.

API keys​

You can generate an API keys via our app. Go to Settings > API keys, and select Create key. Give your key a memorable name and store it somewhere safe.

Your API key determines which endpoints you can access based on your role. If you're not sure of your role, check the Team members list under Settings, or contact your organization admin.

The Griffin API requires an API key to be attached to every request message, using the GriffinAPIKey key within theAuthorization header

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

Key management​

You are responsible for securely managing your API key. Keep in mind:

  • The API key value is only shown once upon creation, so store it somewhere safe. If you lose it, you'll need to log in, delete it and create a new one.
  • You should use an API key value via environment variables (or another secure mechanism) when calling the API to minimise exposure of the key value.
  • Never share your API keys publicly (e.g. do not commit to a shared source control service).
  • If an API key is compromised, log into the app and revoke it immediately.

Message Signatures​

Message signatures for API requests provide an additional layer of security. Each request message includes a cryptographic signature that verifies the sender's identity and ensures the API request hasn't been tampered with.

How can I implement message signatures?​

To implement message signatures, you will need to create a public-private key pair, and register the public key on our app (Settings > Message signatures). You will then need to create a signature for each request message using the private key.

For a step-by-step walkthrough, check out our guide on how to create message signatures.

How to enforce message signatures​

Message signing can be enforced using the ‘Validate all requests’ toggle in our app. View the toggle by navigating to Settings > Message signing.

In the live environment, message signing is mandatory and will be enforced by default. Please contact your customer support manager if you need to disable message signing.

In the sandbox, message signing is optional. You can enforce it by switching the toggle on as shown below.

  • When the toggle is on: all requests must be signed. This mimics your live environment.
  • When the toggle is off: both signed and unsigned requests are accepted, and signed requests are still validated.

Enforce message signatures toggle

Private key management​

Private keys for message signatures must be stored securely. Keep in mind:

  • Private keys can only be used to sign messages for a specific Griffin organisation.
  • To support rotating keys, a message can be signed by more than one private key using a unique signature label name to attach each signature.
caution

If your private key is compromised, log into to the app and revoke the corresponding public key immediately. You should then inform us of the situation, including the earliest suspected time of compromise in your message. Revoking your key may impact your integration with Griffin, so letting us know as soon as possible will help us minimise any impact on your operations and get you set up with a new key pair as swiftly as possible.

You are responsible for keeping your private keys safe and secure. Below, we've laid out some best practice security recommendations to help you protect your business and your customers.

Key rotation​

We recommend rotating your keys at least once per year, in line with industry best practice.

info

You can use multiple signatures in your message requests is useful when rotating cryptographic keys. For more detail, check out our guide on creating message signatures

Storing private keys​

You should always store your private keys with appropriate safeguards. We recommend using a trusted Key Management System (KMS), such as AWS Key Management Service. This is a centralised system for storing and managing your cryptographic keys, with access controls to ensure that only authorised users can view, create, or revoke keys.

If a KMS is not an option, then keys should be stored in a secrets management tool that provides similar benefits, such as AWS Secrets Manager or Hashicorp Vault.

The services mentioned above are illustrative examples only, and you should alway carry out an independent assessment of any tool you use for key storage management.

Encrypting your private keys​

Private keys must be encrypted at rest. KMS and Secrets Managers will likely do this for you.

If you have on disk copies of your private keys, they must be encrypted using a robust algorithm such as AES (Advanced Encryption Standard) and stored in a secure location.

Always use a strong passphrase to encrypt the key, and store it a separate location. This way, even if hackers gain access to your private keys, they will have to crack the password and decrypt the keys, giving you more time to react to the breach.

Limit access​

The only users who should have access to private keys are those who absolutely need them to do their jobs (i.e. access should be granted on the basis of least privilege). Use authentication controls to ensure that only authorised users have access to private keys, and logging mechanisms to track who accessed the keys and when.

Verification monitoring​

You should regularly review the users who have access to your private keys, and monitor and verify all access attempts on a regular basis. This will help you catch any unexpected changes or suspicious activity. You can use software to automate this process, or a hire an independent third party to perform regular audits.