Authentication

All API endpoints require authentication. There are two ways to authenticate, as a user and as a client app. Both ultimately give you a token which you must then include with every API request.

User authentication type—Authentication requests include user credentials, client ID and client secret, and the password grant type. The scope must end with access_as_user.
Client app authentication type—Authentication requests include client ID, client secret, and the client_credentials grant type. The scope must end with .default. Because the token does not include any user information, subsequent requests using a token acquired through client app authentication must include the x-api-caller-id header.

Authentication via API does not change what the authenticated user has access to. Authentication verifies who the API user is, while Keyavi's role-based access determines what data the API user can access. API users also have roles that govern which requests they can make.

User Authentication

To authenticate with the Keyavi API as a user:

Send an HTTP POST request to the Microsoft Online OAuth 2.0 token endpoint with the appropriate parameters. The endpoint URL is https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token, where <tenant-id> is the tenant ID of your Keyavi node. Include these parameters in the request body:
- grant_type: Must contain the value password.
- client_id: The client ID of the registered Keyavi application.
- client_secret: The client secret of the registered Keyavi application.
- scope: The scope is composed of the client ID of the identity provider configured in your Keyavi API authentication app service, followed by /access_as_user . For example, 550e8400-e29b-41d4-a716-446655440000/access_as_user.
- username: The user name used for the configured identity provider.
- password: The password used for the configured identity provider.
  Copy
```
curl --location 'https://login.microsoftonline.com/{tenant-id}>/oauth2/v2.0/token' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'client_id=<Your client ID>' \
--data-urlencode 'client_secret=<Your client secret>' \
--data-urlencode 'scope=api://<Your scope address>/access_as_user' \
--data-urlencode 'username=<Your user name>' \
--data-urlencode 'password=<Your password>'
```
If the authentication succeeds, the token endpoint responds with a JSON response that includes a bearer token.
Store the bearer token securely and in a safe place.

Anyone with this token can perform the authorized actions against the resources that the token has access to.
Use this token to authenticate future API requests by including this header:
Copy
```
Authorization: Bearer {access_token}
```

Client App Authentication

To authenticate with the Keyavi API as a client App:

Send an HTTP POST request to the Microsoft Online OAuth 2.0 token endpoint with the appropriate parameters. The endpoint URL is https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token, where <tenant-id> is Microsoft Entra ID tenant ID. Include these parameters in the request body:
- grant_type: Must contain the value client_credentials.
- client_id: The client ID of the registered Keyavi application.
- client_secret: The client secret of the registered Keyavi application.
- scope: The scope is composed of the client ID of the identity provider configured in your Keyavi API authentication app service, followed by /.default . For example, api://550e8400-e29b-41d4-a716-446655440000/.default.
If the authentication succeeds, the token endpoint responds with a JSON response that includes a bearer token.
Store the bearer token securely and in a safe place.

Anyone with this token can perform the authorized actions against the resources that the token has access to.
Use this token to authenticate future API requests by including this header:

Copy
```
Authorization: Bearer {access_token}
```

HTTP Requests

After you authenticate and successfully receive a bearer token, you're ready to make requests to the Keyavi API. Keyavi APIs only accept HTTPS traffic.

To ensure a detailed audit trail for security purposes, every request must be attributed to a user in the system. For user authentication types, when Keyavi verifies the token, we extract user information to properly attribute subsequent calls. For client app authentication types, the token includes no user information, so subsequent requests using such a token must include the x-api-caller-id header.

HTTP requests to the Keyavi API are composed of:

The base URL which provides the starting point for all requests. Keyavi's base URL is https://<Custom API URL>/api/. The base URL for each environment is configured during Keyavi implementation.
The endpoint which represents the address of the resource you're connecting to. The terms endpoint and resource are often used interchangeably, but in these API docs, we only use endpoint when discussing the URL.
Send the access token received from authorization with every request as an Authorization HTTP header, formatted as Authorization: Bearer {token value}.
Send your subscription key with each request as an HTTP headers, formatted as (Ocp-Apim-Subscription-Key: {subscription key}).
If the access token was created from a client app authentication, the headers must also include the x-api-caller-id, which is the email of the person or service making the request.
Optional query parameters which allow sorting, filtering, and limiting data. See Filtering and Sorting and Pagination for details about using query parameters.
Optional path parameters where you supply the id of a specific resource.

Here's an example with the required headers for a call to the protect-remote resource. Note that since this token was issued for a client app authentication, it includes the x-api-caller-id header.

Copy

curl --location 'https:/<API-URL>/api/payloads/protect-remote/' \
--header 'Authorization: Bearer <ACCESS-TOKEN>'
--header 'Ocp-Apim-Subscription-Key: <YOUR-SUBSCRIPTION-KEY>' \
--header 'x-api-caller-id: <USER-ID-FOR-TOKENS-ISSUED-TO-CLIENT-APPS>' \

Next Step

Get to know the Keyavi resources you can call.