Skip to main content
Version: v2.x

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 client 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 client credentials​

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

A set of API client credentials 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 a set of API client credentials is no longer needed or wanted, the Cyral administrator can delete them from the API Client Credentials page in Cyral.

Create API client credentials​

You must be a Cyral administrator to create API client credentials.

  1. In the Cyral control plane UI, click API Client Credentials in the lower left.

  2. Click the ➕ button. Give the account a name, and give it the needed permissions. Choose one or more from:

    • Access Request: File a request for access to a repository
    • Access Management: Approve, reject, and revoke users' repository access requests.
    • Access Management Proxy Request: Permission for an app such as a Slack app to file a request on a user's behalf for access to a repository
    • Access Management Proxy Manage: Permission for an app such as a Slack app to carry out an admin's actions that may approve, reject, and revoke users' repository access requests.
    • 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.
    • View Datamaps: View the data field mappings used in Cyral policies.
    • Modify Sidecars and Repositories: Add, edit, and view Cyral sidecars and associate them with data repositories.
    • View Sidecars and Repositories: View Cyral sidecar and data repository settings in Cyral.
    • Modify Users: Add, edit, and view user accounts in Cyral.
    • Modify Roles: Add, edit, and view users' roles 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.
    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 a client credentials API token and connect to the API​

When you want to connect a client to the Cyral API, make a POST call to the https://$CYRAL_CONTROL_PLANE:8000/v1/users/oidc/token endpoint, passing in your client ID and 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.

Here's an example script that retrieves a token and then uses it to connect to the /v1/sidecars endpoint.

export CYRAL_CONTROL_PLANE="<Insert your Cyral control plane URL 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:8000/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:8000/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. This approach follows the OAuth 2.0 standard. To get an API token using your refresh token, set the grant_type to refresh_token:

curl -X "POST" "https://{CP URL}:8000/v1/users/oidc/token" \
     -d "grant_type=refresh_token" \
     -d "refresh_token=<...refresh token here...>" \
     -d "client_id=<...client id here...>" \
     -d "client_secret=<...client secret here...>"