Skip to main content

Using API Keys in RAW

API Keys provide a way to associate consumer keys to endpoint scopes, so that clients can consume endpoints securely.

The access to the API Keys view is done via selecting the API Keys tab of the left sidebar

RAW_Labs api-keys

Below you can observe the API Keys view:

API Keys

In this view, you can observe the API keys of your application, along with the following metadata:

  • Name: The name of the API key. Useful for identifying them quickly.
  • Key: The actual key, hidden from plain sight. You can reveal it (please be cautious) and copy it so that you can share it with your clients of interest.
  • Expires At: Date until the API Key is considered valid. Recommended being short term. After that date, the key will be considered invalid.
  • Status: Whether the key is active or not. In case of a potential leak, or for your own business reasons, you can deactivate the key, and perhaps activate it again any time required.
  • Scopes: The endpoint scopes that the key is bound with. An API Key can be related to as many endpoint scopes as you may like, as these are defined in your endpoint yml files.

Add a new API Key​

Assuming the endpoint ISS/isslocation contains the scope ISS, as per the screenshot below, when we request a new API key, we will relate this API key to this scope.

ISS endpoint

Below you can see the form to request a new API key. We set the key as active from start, we add the expiration time 1 month from now, and we relate the iss scope to the key.

new API key form

After clicking 'Done', we will get a visual notification on the right side of our screen that key was generated successfully, and we can observe it in the table, as per the image below:

API key listing

In the scopes column, you can observe the list of scopes that this API key is bound with. On the right, using the details button, you can observe the API key configuration, i.e. the expiration date, the scopes that are bound with it, and you can perform two actions; Activate/deactivate the key, or delete the key, as per the below example.

API key details

Consume an endpoint with your API Key​

If we hover over the key column of the table, and left click, we will copy the actual key in our clipboard. After that, we can invoke the endpoint using the key via this custom header:

-H X-RAW-API-KEY:${OUR_KEY_HERE}

As per example, we will demonstrate a curl request with this API key:

curl -H 'X-RAW-API-KEY:OUR_COPIED_API_KEY_HERE' 'https://dev-nuhynxsvnkentel.raw-labs.com/docs-raw-labs/1/public/ISS/isslocation' | jq .

"Shandan County, 734100 Gansu, China"

Retrieve OpenAPI specification with your API Key​

API Keys offer an additional functionality, allowing users to effortlessly obtain the OpenAPI specification for the endpoints associated with their key.

This can be achieved by including the X-RAW-API-KEY header in the request directed towards the /raw/1/api/admin/endpoints/open-api endpoint.

curl -H 'X-RAW-API-KEY:OUR_COPIED_API_KEY_HERE' 'https://dev-nuhynxsvnkentel.raw-labs.com/raw/1/api/admin/endpoints/open-api' | jq .

The response will encompass the OpenAPI specification for the endpoints accessible with the provided API key. This includes private endpoints linked to the granted scopes of the key, along with both public and private endpoints that do not require specific scopes.