Connect to the Cyral API

You can build applications that connect to the Cyral API to help manange or monitor your users' access to data repositories. For example, you might wish to build an access requests and approvals application to let people get self-service access to a database. Below, we show how such applications can connect to the Cyral API.

To connect to the Cyral REST API, you'll need an API token. One way to get a token is by submitting your Cyral API access key credentials: your client ID and client secret. With these, you'll get an expiring token that allows you to connect. Once the token expires, you must re-authenticate with your client ID and client secret, or with a refresh token.

API access key

An API access key is an account your application will use to retrieve its API token. Each API access key has a set of permissions that your Cyral administrator has assigned, dictating the types of API calls the application is allowed perform.

An API access key is secured using its client secret. At any time, the Cyral administrator can rotate the client secret, which forces the user of those credentials to use the new secret in subsequent connections.

When an API access key is no longer needed or wanted, the Cyral administrator can delete it from the API Access Keys page in Cyral.

Create an API access key

You must be a Cyral administrator to create an API access key.

1. In the Cyral control plane UI, click API Access Keys in the lower left.

2. Click the ➕ button. Give the account a name, and give it the needed permissions, also known as the Cyral API roles. Choose one or more from:

   • Approval Management: Create and manage users' repository access requests. This permission grants the ability to submit an access request as well as the ability to approve, deny, or revoke an access request.
   • Modify Integrations: Add and remove Cyral system integrations, such as a logging or messaging integration.
   • Modify Policies: Add, edit, and view access policies and Data Maps.
   • Modify Roles: Add, edit, and view users' roles in Cyral.
   • Modify Sidecars and Repositories: Add, edit, and view Cyral sidecars and associate them with data repositories.
   • Modify Users: Add, edit, and view user accounts in Cyral.
   • Repo Crawler: Run periodic scans of repositories to check for data fields to be protected.
   • View Audit Logs: Read logs of activity in Cyral.
   • View Datamaps: View the data field mappings used in Cyral policies.
   • View Integrations: View Cyral system integrations, such as a logging or messaging integration.
   • View Policies: View access policies and Data Maps.
   • View Roles: View users' roles in Cyral.
   • View Users: view user accounts in Cyral.

   warning

   The permissions Modify Roles and Modify Users grant permissions to modify any role or user. It means that users granted these permissions are able to modify their own roles or users and grant more privileges.

3. Click Create.

4. The client ID and client secret are displayed. Copy them and store them in a secure location. You will use these values to get a Cyral API token for establishing an API session.

tip

If you lose your client ID or client secret, click the Rotate secret button to get new credentials. Your old client secret will become invalid when you do this.

Get an API token

When you want to connect a client to the Cyral API, make a POST call to the https://$CYRAL_CONTROL_PLANE_DOMAIN/v1/users/oidc/token endpoint, providing in your client ID and client secret as follows.

export CYRAL_CONTROL_PLANE_DOMAIN="<Insert your Cyral control plane domain here>"
export CYRAL_CLIENT_ID="<Insert your client ID here>"
export CYRAL_CLIENT_SECRET="<Insert your client secret here>"

curl --request POST "https://$CYRAL_CONTROL_PLANE_DOMAIN/v1/users/oidc/token" \
  -d grant_type=client_credentials \
  -d client_id="$CYRAL_CLIENT_ID" \
  -d client_secret="$CYRAL_CLIENT_SECRET"

If your credentials are valid, the call returns a JSON response that contains a client credentials-type API token for connecting. Here's an example response:

{ 
   "access_token": "eyJhbGciO...hBXjec-Sw",
   "expires_in": "300",
   "refresh_expires_in": "36000",
   "refresh_token": "eyJhbGciO...RZqN0",
   "token_type": "bearer",
   "not_before_policy": "0",
   "session_state": "cd...18",
   "scope": "email profile"
}

The access_token within the JSON response is the short-lived API token that can be used to make calls to the Cyral API. This token expires five minutes from when it was issued. Set your application to retrieve a new token when it expires, or use a longer-lived refresh token as shown in the next section.

Make an authorized API request

Here's an example script that retrieves a token and then uses it to fetch a list of sidecars.

export CYRAL_CONTROL_PLANE_DOMAIN="<Insert your Cyral control plane domain here>"
export CYRAL_CLIENT_ID="<Insert your client ID here>"
export CYRAL_CLIENT_SECRET="<Insert your client secret here>"

TOKEN=$(curl --request POST "https://$CYRAL_CONTROL_PLANE_DOMAIN/v1/users/oidc/token" \
  -d grant_type=client_credentials \
  -d client_id="$CYRAL_CLIENT_ID" \
  -d client_secret="$CYRAL_CLIENT_SECRET" | jq -r .access_token)
SIDECARS=$(curl "https://$CYRAL_CONTROL_PLANE_DOMAIN/v1/sidecars" -H "authorization: Bearer $TOKEN")

echo $SIDECARS | jq

Get an API token using a refresh token

Cyral supports getting API tokens using longer-lived refresh tokens following the OAuth 2.0 standard. To get an API token using your refresh token, set grant_type to refresh_token and provide your refresh token in the request body:

export CYRAL_CONTROL_PLANE_DOMAIN="<Insert your Cyral control plane domain here>"
export CYRAL_CLIENT_ID="<Insert your client ID here>"
export CYRAL_CLIENT_SECRET="<Insert your client secret here>"
export CYRAL_REFRESH_TOKEN="<Insert your refresh token here>"

curl -X "POST" "https://$CYRAL_CONTROL_PLANE_DOMAIN/v1/users/oidc/token" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=$CYRAL_REFRESH_TOKEN" \
  -d "client_id=$CYRAL_CLIENT_ID" \
  -d "client_secret=$CYRAL_CLIENT_SECRET"