> ## Documentation Index
> Fetch the complete documentation index at: https://docs.automaticrostering.visma.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Learn how to authenticate to the API

## Getting API Access

Follow the steps below to receive the credentials you need when making API calls.

<Steps>
  <Step title="Access the Visma Developer Portal">
    Log in to the appropriate environment in the Visma Developer Portal:

    * [**Stage environment** (for testing)](https://oauth.developers.stagaws.visma.com/service-registry/apistore/automatic-rostering)
    * [**Production environment** (for end-users)](https://oauth.developers.visma.com/service-registry/apistore/automatic-rostering)
  </Step>

  <Step title="Create a new application">
    Go to "My Applications" and click "Add Application" > "Service
    (Machine-to-Machine)".
  </Step>

  <Step title="Configure and publish your application">
    Fill in the required details and save your application. Make sure to note your
    `client_id`, then publish the application to make it available for
    integration.
  </Step>

  <Step title="Add a new integration">
    Open your application, add a new integration, and search for `Automatic Rostering`.
  </Step>

  <Step title="Configure the integration">
    Select the `Automatic Rostering` API and the `automatic-rostering:full` scope for your integration.
  </Step>

  <Step title="Wait for approval">
    Wait for the integration to be accepted. Feel free to contact the Automatic
    Rostering team to expedite the process.
  </Step>

  <Step title="Generate and store credentials">
    Open your application, generate credentials, and securely store the `client_secret`.
  </Step>
</Steps>

## Retrieving and Using JWT Tokens

Once you have your `client_id` and `client_secret`, you can retrieve a JWT access token to authenticate your API requests.

### Retrieve an Access Token

To retrieve an access token, make a `POST` request to the Visma Connect token endpoint:

<AccordionGroup>
  <Accordion title="Stage Environment">
    **Endpoint:** `https://connect.identity.stagaws.visma.com/connect/token`

    **Request:**

    ```bash theme={null}
    curl -X POST https://connect.identity.stagaws.visma.com/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=automatic-rostering:full"
    ```
  </Accordion>

  <Accordion title="Production Environment">
    **Endpoint:** `https://connect.visma.com/connect/token`

    **Request:**

    ```bash theme={null}
    curl -X POST https://connect.visma.com/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=automatic-rostering:full"
    ```
  </Accordion>
</AccordionGroup>

**Response:**

```json theme={null}
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600,
  "token_type": "Bearer"
}
```

### Use the Token in API Requests

Include the access token in the `Authorization` header of all requests to the Automatic Rostering API:

```bash theme={null}
curl -X POST https://api.automaticrostering.visma.net/roster/start \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

<Note>
  The access token expires after a certain period (typically 3600 seconds). You'll need to retrieve a new token when it
  expires. Make sure to implement token refresh logic in your application.
</Note>