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

## 1. 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.


## 2. 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.

**Token Endpoint**:

```bash
POST https://api.eu.quinyx.com/oauth/v3/token
```

### Example Request

```shell curl
curl -i -X POST \
  'https://api.{region}.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 organization:groups:create'
```

### Example Response

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

```json 400 application/json
{
  "error": "unsupported_grant_type",
  "error_description": "Unsupported grant type: invalid_type"
}
```

```json 401 application/json
{
  "error": "invalid_client",
  "error_description": "Client not found: my-client-id"
}
```

```json 500 application/json
{
  "error": "server_error",
  "error_description": "Token generation failed"
}
```

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).

## 3. Call Your First API Endpoint

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

### Example: List groups

```shell curl
curl -i -X GET \
  'https://api.{region}.quinyx.com/organization/v3/groups' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
```

### Example Response

```json 200 application/json
{
  "data": [
    {
      "id": "42",
      "name": "Engineering",
      "groupType": "UNIT",
      "parentGroupId": "10",
      "managerId": "1001",
      "costCentreId": "200",
      "xrefIds": [
        "AD-ENG",
        "COST-ENG-01"
      ],
      "created": "2024-01-10T09:15:30Z",
      "updated": "2024-01-12T17:42:10Z"
    }
  ],
  "pagination": {
    "nextPageToken": "eyJpZCI6MTIwfQ",
    "previousPageToken": "eyJpZCI6ODB9"
  }
}
```

```json 400 application/problem+json
{
  "type": "https://developer.quinyx.com/api/problems/bad-request",
  "title": "Bad Request",
  "status": 400,
  "detail": "The request is invalid or malformed",
  "instance": "/organization/v3/groups"
}
```

```json 401 application/problem+json
{
  "type": "https://developer.quinyx.com/api/problems/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Access token not set or invalid, and the requested resource could not be returned",
  "instance": "/organization/v3/groups"
}
```

```json 403 application/problem+json
{
  "type": "https://developer.quinyx.com/api/problems/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "The resource could not be returned as the requestor is not authorized",
  "instance": "/organization/v3/groups"
}
```

```json 500 application/problem+json
{
  "type": "https://developer.quinyx.com/api/problems/server-error",
  "title": "Server Error",
  "status": 500,
  "detail": "The server encountered an unexpected error",
  "instance": "/organization/v3/groups"
}
```

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

## 4. Next Steps

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