# Make Your First API Call

This guide walks you through authentication, obtaining an access token, and making your very first request against the Quinyx API.

## Before you start

- **Access to Integrations credentials** ([Generate](https://web.quinyx.com/))

  Credentials are generated under **Account Settings → Integrations credentials**, so you need an account with access to that page.

- **Token with proper scopes**

  An API credential with `hr:groups:read` scope.

### Get Your API Credentials

Before you can use the API, you need credentials.

Each credential set contains:

* **Client ID**: identifies your integration
* **Client Secret**: private key used for authentication
* **Scopes**: permissions defining what your integration can access


Credentials are generated in **Integrations credentials** page.

To create a new API credential:

1. Log in to Quinyx
2. Navigate to **Account Settings → Integrations credentials**
3. Click **Generate credentials**
4. Choose a name for the credential, select `Version 3`, and click Save.
5. Copy the Client ID and Client Secret (you’ll need these for authentication).
6. Assign the appropriate scopes (permissions) for your integration.


### Authenticate with OAuth 2.0

Quinyx uses the OAuth 2.0 for authentication. You will need to request a bearer token and use it in all subsequent requests.

**Example request**

```bash
curl -X POST 'https://api.eu.quinyx.com/oauth/v3/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials' \
  -d 'client_id=my-client-id' \
  -d 'client_secret=my-client-secret' \
  -d 'scope=organization:groups:read'
```

**Example response**

200 application/json
```json 200 application/json
{
  "access_token": "eyJhbGciOiJSUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "organization:groups:read"
}
```

The `access_token` must be passed in every request to the API using the `Authorization: Bearer` header. Tokens expire after the time defined in `expires_in` (usually 3600 seconds = 1 hour).

### Call Your First API Endpoint

With your token in hand, add it to the `Authorization` header using the **Bearer** scheme.

**Example: List groups**

```bash
curl 'https://api.eu.quinyx.com/organization/v3/groups' \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...'
```

**Example response**

200 application/json
```json 200 application/json
{
  "data": [
    {
      "id": "1",
      "name": "My district",
      "groupType": "DISTRICT",
      "managerId": "87",
      "xrefIds": [
        "my_external_id_10"
      ],
      "created": "2025-01-01T12:00:00Z",
      "updated": "2025-01-01T12:00:00Z"
    },
    {
      "id": "2",
      "groupType": "UNIT",
      "name": "My unit",
      "parentGroupId": "1",
      "managerId": "87",
      "costCentreId": "1",
      "xrefIds": [
        "my_external_id_11"
      ],
      "created": "2025-01-01T12:00:00Z",
      "updated": "2025-01-01T12:00:00Z"
    },
    {
      "id": "3",
      "groupType": "SECTION",
      "name": "My section",
      "parentGroupId": "2",
      "managerId": "87",
      "costCentreId": "1",
      "xrefIds": [
        "my_external_id_12"
      ],
      "created": "2025-01-01T12:00:00Z",
      "updated": "2025-01-01T12:00:00Z"
    }
  ],
  "pagination": {
    "nextPageToken": "cHJldmlvdXNUb2tlbg"
  }
}
```

✅ You’ve successfully obtained an access token and called your first Quinyx API endpoint!

## Next Steps

* Browse [other guides](/guides)
* Explore endpoints in the [API Reference](/api/v3/specs/quinyx-public-api-v3)
* Try out requests with your token to start building integrations