Okra API

Welcome to the Okra API Reference, the central hub for developers looking to unlock the power of open banking. Use this API intro page to understand how you can interact with Okra’s API, and what best practices you can adopt to make the most of your integration.

Authentication

Okra’s API uses bearer authentication. There are 3 kinds of keys you must use in your implementation:

• The client token is a unique ID that represents you, as a client. You must use it together with your public API key in your implementation. Client tokens can be used in both Sandbox and Production environments.
• The public API key, along with the client token is used to authenticate your Okra implementation.
• The secret API key is an encoded JSON Web Token that you must use for authentication on the API level.

Some notes about Okra’s API keys:

• Public API keys can be published and renewed.
• Secret API keys should be kept secure and should not be surfaced publicly.
• Okra provides separate keys for sandbox and production data. The production API key grants access to real-time data, while the sandbox API key grants access to test data. Make sure that you always use each key in its correct environment.

Visit the Okra Dashboard to retrieve your API keys.

API environments

Okra’s Identity API operates in two environments: sandbox and production.

Interacting with the API

Postman

You can use Postman to test your integration and the data sets that the Okra API offers. Click on this button and fork the collection:

Use environment variables to customize the requests that you send. This step is optional, but can help you avoid mixing up environments and credentials. Read more in Postman's docs on managing environments.

Requests

The Okra API accepts POST and GET requests. Your requests must follow these formal requirements:

• The authorization header must contain your secret API key as a bearer token.
• The content-type header must be application/json.
• The request body must be in valid JSON format.

Rate limiting

Requests to the Okra API are rate limited at 60 requests per minute. If you exceed this limitation, the API responds with a 429 - Too many requests error.

The API returns information about the applied rate limits in the header of every response:

• X-RateLimit-Limit shows the total number or requests that the API allows in one minute.
• X-RateLimit-Remaining shows the number or remaining requests in the current time window.
• X-RateLimit-Reset shows the time in UNIX epoc seconds when the current rate limit window resets.
• Retry-After shows the amount of time you need to wait before you can resume calling the API.

We recommend that you implement a retry in your app that responds to the 429 - Too many requests error. Scale down your request frequency and retry your rate limited requests according to the value of Retry-After.

Responses

The Okra API responds with HTTP codes to indicate status and errors. The API provides all responses in standard JSON format.

null fields

When no information is present, data fields may return null values:

{
    "status":"success",
    "message":"Data successfully retrieved",
    "data":{
        "details":{
            "name":"Peter Jones",
            "address": null"
        }
    }
}

Pagination

Endpoint operations that return multiple data sets use paginated responses. Use the limit and page parameters to control the number of results that you want to receive in a response:

• limit limits the number of results that the API returns in a single page. If you do not specify a value for this parameter, the API will limit the response to 10 results per page.
• page returns a specific page of results. For example, if you set limit to 20 and set page to 1, the API will return the first page, with 20 results in the response.

Next steps

• Visit the Onboarding guide to get started with your implementation
• If you bump into technical issues during your integration, you can open a ticket on Okra's Support portal or get in touch with Okra’s support team directly.