Using API Keys

What is an API Key?

An API Key is a unique string of characters that is used to authenticate requests to an API. It acts like a secret token that identifies the calling application or user, allowing the API to verify that the requester has permission to access the requested resources or perform certain operations.

In this API, API Keys are used as one of the methods to authorize access to specific endpoints, particularly for machine-to-machine communication or for clients that cannot use standard token-based authentication flows (like SSO or DeskToken).

How to Use an API Key

When making a request to an endpoint that supports API Key authentication, you need to include the API Key in the HTTP request headers.

For this specific API, the API Key should be sent in a header named:

X-API-Key

Example Request

Here's a conceptual example of how you might make a request using a tool like curl. Replace YOUR_API_KEY with your actual API key and https://your-api-domain.com/approvals/GetApprovalNotComplete with the actual endpoint URL.

Endpoints Supporting API Key Authentication

In the ApprovalsController (version 2), the following endpoints are configured to allow API Key authentication (alongside SSO or DeskToken):

GET /approvals/GetApprovalNotComplete (requires "read" scope if API Key is used)

POST /approvals/UpdateApprovalStatus (requires "write" scope if API Key is used)

POST /approvals/CreateApproval (requires "write" scope if API Key is used)

The specific scopes ("read" or "write") associated with an API Key determine which of these operations it can perform. This is typically configured when the API Key is generated or managed.

Security Best Practices

Keep your API Key secret: Treat your API Key like a password. Do not embed it directly in client-side code or commit it to version control systems.

Use HTTPS: Always make API requests over HTTPS to ensure that the API Key (and other sensitive data) is encrypted in transit.

Principle of Least Privilege: Ensure API keys are granted only the necessary permissions (scopes) required for their intended use.

Regenerate Keys if Compromised: If you suspect an API Key has been compromised, regenerate it immediately and update your applications.

Environment Variables: Store API keys in environment variables or secure configuration management systems on the server-side rather than hardcoding them.

This guidance should help you understand how to use API keys with this API.

What is an API Key?#

How to Use an API Key#

Example Request#

Endpoints Supporting API Key Authentication#

Security Best Practices#

What is an API Key?

How to Use an API Key

Example Request

Endpoints Supporting API Key Authentication

Security Best Practices