# 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:

GraphQL API workflow overview
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)**


```bash
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**


```json
{
  "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.


```http
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
```