Skip to main content

Using API Keys in RAW

API Keys allow you to associate consumer keys with endpoint scopes, ensuring that clients can securely access your endpoints.

To view and manage your API Keys, select the API Keys tab on the left sidebar.

API Keys

Ιn the API Keys view, you can manage the keys associated with your application. Each API Key is displayed with the following metadata:

  • Name: The identifier for the API Key, helping you quickly locate and differentiate keys.
  • Key: The actual API Key, hidden by default for security. You can reveal and copy it when needed—be cautious when sharing it with clients.
  • Expires At: The expiration date of the API Key. It’s recommended to set short-term expiration dates for enhanced security. After this date, the key becomes invalid.
  • Status: Indicates whether the API Key is active or inactive. If needed (e.g., due to a potential security leak or business requirements), you can deactivate * and reactivate the key at any time.
  • Scopes: The endpoint scopes associated with the key. An API Key can be linked to multiple endpoint scopes, as defined in your endpoint .yml files. This ensures secure and granular access control.

Add a new API Key​

Let's assume that the endpoint salesforce/api/cases/read contains the scope case_assistant:admin. When requesting a new API key for the salesforce/api/cases/read endpoint, which is associated with the case_assistant:admin scope, follow these steps (as shown in the screenshot):

  • Set the Key Status: Ensure the API key is active from the start.
  • Define Expiration Time: Set the expiration date for one month from the current date. This ensures the key remains valid for a limited time, enhancing security.
  • Assign Scope: Link the API key to the case_assistant:admin scope, granting the appropriate level of access to the endpoint.
  • Click Done: Finalize the API key creation. This process creates a secure API key tied to the specific scope, ensuring controlled access to the salesforce/api/cases/read endpoint.

new API key form

In the Scopes column, you can view the list of scopes associated with each API key.

On the right side, click the ... menu and select Edit to view or modify the API key configuration. This includes:

  • The expiration date of the key.
  • The scopes linked to the key. If needed, you can deactivate the key by clicking the Deactivate button. This action temporarily disables the key, preventing its use until reactivated.

API key details

Consume an endpoint with your API Key​

You can copy the actual API key to your clipboard by clicking the copy icon in the Key column. Once copied, you can use the key to invoke the endpoint by including it in the request with the following custom header:

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

Retrieve OpenAPI specification with your API Key​

API Keys provide an additional feature that allows users to easily retrieve the OpenAPI specification for the endpoints associated with their key.

To fetch the OpenAPI specification for endpoints linked to your API key, include the X-RAW-API-KEY header and send the request to the endpoint /raw/1/api/admin/endpoints/open-api.

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 include the OpenAPI specification for all endpoints accessible with the provided API key. This encompasses:

  • Private endpoints associated with the scopes granted by the API key.
  • Both public and private endpoints that do not require specific scopes. This ensures comprehensive access to the relevant API specifications based on the key’s permissions.