Authentication

How to send your secret API key with every request, and where to find your keys and webhook settings in the Dashboard.

This page shows how to authenticate API requests with your secret API key and how to set up webhooks in the Dashboard.

API keys

Every request to the Gravv API needs your secret API key in the Api-Key header:

Api-Key: grvSec_<sandbox|live>_…

You have one secret key for each environment. A key that starts with grvSec_sandbox_ reaches sandbox, and a live key reaches live. The Dashboard also shows a Public Key, but no API endpoint uses it.

Your API key identifies your business and environment. Gravv reads the business from the key, so there is no tenant header to send. Gravv ignores any tenant header you send.

Keep your API keys secret. Don't put them in GitHub repositories, client-side code, or anywhere other people can read them. Send all requests over HTTPS.

Obtain and use your API keys

To get your API key:

1. Sign in to your Gravv Dashboard with your registered business email address.
2. Turn on Sandbox mode for testing, or Production for live.
3. Click Manage in the side navigation.
4. Click Configure under the Manage section.
5. Click API keys, then click the copy button under Secret Key to copy your Secret Key.
6. Use the copied Secret Key as the Api-Key in your request header:

curl -X POST https://api.gravv.xyz/v1/customers \
  -H "Api-Key: <API_KEY>" \
  -H "Idempotency-Key: <a new UUID for this request>" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "Doe",
    "middle_name": "Sample",
    "email": "jane.doe@example.com",
    "phone": "+2348031230101",
    "type": "individual",
    "gender": "female",
    "date_of_birth": "1992-04-16",
    "address": {
      "address_line1": "Same Global Housing Estate",
      "city": "Lokogoma",
      "country": "NG",
      "postal_code": "900107",
      "state": "NG-FC"
    }
  }'

Replacing a key

When you create a new secret key for an environment, Gravv deletes the previous key for that environment. Update every system that uses the old key at the same time. A deleted key can keep working for up to 2 minutes, because Gravv caches key checks for that long. A new key works at once.

Authentication errors

A request that fails authentication returns HTTP 401 with a message in error:

Message	Cause
Invalid token!	The key is unknown, deleted or malformed
Invalid Api Key header. Api-Key is required!	No Api-Key header, on an endpoint that accepts only API keys
Invalid Authorization header. Bearer token or Api-Key is required!	No Api-Key header, on an endpoint that also serves the Dashboard

{
  "data": null,
  "error": "Invalid token!"
}

If your key is limited to certain permissions, a request outside them returns HTTP 403 with the permissions it needs:

{
  "data": null,
  "error": {
    "reason": "forbidden",
    "required_any": [
      "transfer:initiate"
    ]
  }
}

Webhooks

You set up webhooks in the Dashboard. There is no API for it. You register one URL for each environment, and Gravv sends every event type to it.

To create a webhook:

1. Follow steps 1 through 4 in Obtain and use your API keys, with the environment you want selected.
2. Click Webhooks.
3. Click Create Webhook to open the form.
4. Enter your webhook endpoint in the Webhook URL field. It must be a public https URL.
5. Click Generate to create your webhook secret. It starts with whsec_. Save it. You need the whole value, whsec_ included, to verify signatures.

Sandbox and live each have their own webhook URL and secret. To change the URL or the secret, edit the webhook. A change can take up to 5 minutes to apply, so accept signatures made with the old secret or the new one for at least 5 minutes after you save a new secret.