Requests

Introduction

Due to security considerations, almost all but the most trivial endpoints require some form of Authorization before access is granted to the resources behind.

Rate Limits

To prevent abuse of the service, rate limits are applied on all authorized calls made to the API.

🚧

Current Global Limits

All authorized users are limited to 60 calls/min

When the limit is exceeded, the API returns responses with status code 429 Too Many Requests during the cool down. See Status Codes for more information.

Idempotency

The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. This is useful in situations where you'd like to prevent duplicate actions from your service. For example, if a request to create a payment does not return a response, due to a network connection error, you can retry the request with the same idempotency key to guarantee that no more than one payment is executed.

To perform an idempotent request, provide an additional x-idempotency-key: <key> header to the request.

Idempotency on the API works by only considering the idempotency key provided in the request, regardless of whether it succeeded or failed. Subsequent requests with the same key will return a error with a 409 Conflict status code.

An idempotency key is a unique value generated by the client which the server uses to recognize subsequent retries of the same request. How you create unique keys is up to you, but we suggest using V4 UUIDs, or another random string with enough entropy to avoid collisions. There is no restriction on the length of an idempotency key, but we recommend a string between 34 (like a UUID) and 255 characters long.

Keys will be automatically purged from the system after they're at least 7 days old, and a new request is generated if a key is reused after the original has been pruned.

All PATCH, POST and PUT requests accept idempotency keys. Sending idempotency keys in GET and DELETE requests has no effect and will be ignored, as these requests are idempotent by definition.

Resources

Many endpoints on the API return resources in one form or the other; they're returned either as Items or Collections (see Responses section).

You'll notice one particular attribute that's always contained within Items is called embed.

{
  "data": {
    "embeds": [
      "customer",
      "added_by_user"
    ],
    "id": "tag_JZYCnWZcMFeNroIW8GbfB",
    "tag": "utilities",
    "description": null,
    "is_trashed": false,
    "deleted_at": null,
    "created_at": "2020-06-11T10:07:00+01:00",
    "updated_at": "2020-06-11T10:07:00+01:00"
  }
}

The embed key always holds a list of all relationships on the item that are available for retrieval - some might be returned by default, but it's also possible for you to request them explicitly.

You can specify the relationships to retrieve explicitly, you'll need to add an additional parameter to the query part of the API endpoint called include with a comma-separated list of the desired relationships.

For instance, using the example above, if we want to retrieve all the available relationships, we'll make a call like so:

curl --location --request GET 'https://sandbox-api.getbrass.co/tags/tag_JZYCnWZcMFeNroIW8GbfB?include=added_by_user,customer' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJhdXRoLmdldGJyYXNzLmNvIiwiZXhwIjoyNTYwMTk4NDUzLCJpYXQiOjE1ODI1ODI0NTMsIm5iZiI6MTU4MjU4MjQ1MywiYXBpX2NsaWVudCI6ImFwcF82UmJCYmR2Q252d3E1bUl2cGN1MHZoIiwiY3VzdG9tZXIiOiJjdXNfNzNHc0JiQzJYZk9tS2JCYTd1Z3NCSiIsInVzZXIiOiJ1c3JfN2psMG0xT2FHZEdMVWlsVjdjc3NrRSJ9.ciHQubNrGKbYz8Qusf7bMmE-zmRVb64t8eEqpO--ouZKFoNYtMWnJzcEbl7rClKh3JeXwGe77KfqwLK2TUOEmQXyeVuwxolnnyXpY1td-Uhp6Ye9fC3G9yhPS0Zc56VUCQ-T48DCB32qYA6Zfy0iKHTrAObdRvRMZigce1414MU'

{
    "data": {
        "embeds": [
            "customer",
            "added_by_user"
        ],
        "id": "tag_JZYCnWZcMFeNroIW8GbfB",
        "tag": "utilties",
        "description": "Mostly for payment items to mark utilities",
        "is_trashed": false,
        "deleted_at": null,
        "created_at": "2020-06-11T10:07:00+01:00",
        "updated_at": "2020-06-11T10:48:44+01:00",
        "added_by_user": {
            "data": {
                "embeds": [
                    "addresses",
                    "customers",
                    "role",
                    "partner",
                    "octane_role"
                ],
                "id": "usr_7jl0m1OaGdGLUilV7csskE",
                "firstname": "Chris",
                "lastname": "Brown",
                "phone": "+2348123456789",
                "password": null,
                "email": "[email protected]",
                "remember_token": null,
                "gender": "male",
                "photo_url": "https://s3.eu-west-1.amazonaws.com/sandbox-private.getbrass.co/cus_73GsBbC2XfOmKbBa7ugsBJ/7e650003-0fea-43c3-a0d7-2fb5e39205f8.jpg",
                "email_verified": false,
                "email_verified_at": null,
                "disabled_at": null,
                "is_trashed": false,
                "deleted_at": null,
                "created_at": "2020-01-04T17:18:54+01:00",
                "updated_at": "2020-10-22T14:08:53+01:00",
                "preferences": {
                    "security": {
                        "enabled_2fa": true,
                        "otp_channel": "email"
                    }
                }
            }
        }
    }
}