Authentication and Endpoints

The Retarus GraphQL API uses the OAuth2 client credentials flow for secure, token-based authentication. This two-step process ensures your credentials remain secure while providing time-limited access tokens for API calls.

API workflow overview

The following diagram illustrates the complete workflow for accessing Retarus reporting data through the GraphQL API:

This two-phase process ensures secure access to your reporting data:

Authentication phase: Your application obtains a time-limited access token using OAuth2 client credentials.
Data retrieval phase: The access token authenticates your GraphQL queries to retrieve reporting data.

The sections below provide detailed implementation guidance for each step of this workflow.

Prerequisites

Before you begin using the API, you'll need these credentials and identifiers from your Retarus account setup:

Your Customer ID—the unique identifier for your Retarus account
Your assigned Client ID and Client Secret—OAuth2 credentials for API authentication

Contact your Retarus account manager if you don't have these credentials.

API endpoints

The API uses separate endpoints for authentication and data retrieval to provide secure, scalable access to your reporting data.

Purpose	Endpoint URL
GraphQL API	`https://api.retarus.com/stable/external-reporting-service/v1`
OAuth2 Token	`https://api-auth-service.eu.retarus.com/realms/platform/protocol/openid-connect/token`

Obtaining an OAuth2 access token

To call the Reporting GraphQL API, you must first obtain an OAuth2 access token using the client credentials flow. Access tokens are short-lived to maintain security while allowing sufficient time for your reporting operations.

Token Request (HTTP POST)

Send to: https://api-auth-service.eu.retarus.com/realms/platform/protocol/openid-connect/token

Parameters (application/x-www-form-urlencoded)

Parameter	Value/Description
`grant_type`	`client_credentials`
`client_id`	Your assigned Client ID
`client_secret`	Your assigned Client Secret
`scope`	`openid`

Example token request (curl)

curl -X POST https://api-auth-service.eu.retarus.com/realms/platform/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=openid"

Example response

{
  "access_token": "eyJhbGciOiJSUzI1...<token-omitted>...",
  "expires_in": 300,
  "refresh_expires_in": 0,
  "token_type": "Bearer",
  "not-before-policy": 0,
  "scope": ""
}

Using the access token for API calls

Use the access token to authenticate GraphQL API calls. All GraphQL requests must be sent as POST requests to /stable/external-reporting-service/v1 with the Authorization header. Remember to refresh your token before it expires to maintain uninterrupted access.