Skip to main content

Service Principal Authentication

What is a Service Principal?​

A service principal is a non-human identity used for machine-to-machine (M2M) communication with the TANGO platform. Instead of logging in with an email and password, a service principal authenticates using an OAuth2 client ID and client secret via the Client Credentials grant type.

Use a service principal when:

  • An automated pipeline or background service needs to call TANGO APIs without human interaction.
  • You want to integrate an external system (e.g., a data ingestion job, a CI/CD pipeline) with TANGO.
  • You need an identity that can be individually audited, rotated, or revoked independently of any user account.

Setting Up a Service Principal​

1. Register an OAuth2 Application​

To obtain a client ID and client secret, register an OAuth2 application in the TANGO dashboard:

  1. Log in to the TANGO Dashboard as a workspace supervisor or administrator.
  2. Navigate to the OAuth Applications section.
  3. Create a new application with the client_credentials grant type.
  4. Copy the generated client_id and client_secret — the secret is shown only once.

2. Obtain an Access Token​

Use the POST /o/token/ endpoint of the Auth API to exchange your credentials for a JWT access token:

curl -X POST <AUTH_API_SERVER>/o/token/ \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=<your_client_id>&client_secret=<your_client_secret>&workspace=<your_workspace>"

A successful response looks like:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 36000,
  "scope": "read write"
}
note

If you omit the workspace field, the token will not be workspace-scoped. Most TANGO API operations require a workspace-scoped token.

3. Use the Token​

Include the access token in the Authorization header of your API requests, exactly like a regular user token:

curl -X GET <PUBLIC_API_SERVER>/api/tango_model \
  -H "Authorization: Bearer <your_access_token>"

Token Lifetime and Rotation​

  • Tokens expire after the duration indicated by expires_in (in seconds).
  • When a token expires, request a new one using the same POST /o/token/ call with your client credentials.
  • Unlike user tokens, there is no refresh token in the Client Credentials flow — always re-authenticate to get a fresh token.

Security Considerations​

  • Store client_id and client_secret as secrets in your deployment environment (e.g., environment variables, a secrets manager). Never hardcode them.
  • Grant service principals only the workspace access they need.
  • Rotate client secrets periodically. You can revoke and regenerate a secret in the TANGO dashboard without changing the client ID.
  • Service principal tokens are audited separately from user tokens — you can identify API activity by the client_id in platform logs.

See Also​