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

# Authentication

This reference provides precise specifications for authenticating API requests. All requests to the Quivo API require authentication using a session token. This ensures that only authorized users can access your account data and perform operations on your behalf. For step-by-step instructions, see the [Make your first API call](/docs/introduction/first-api-call) tutorial.

The authentication process consists of the following steps:

1. **Obtaining a session token:** Exchange your API credentials—API key, username, and password—for a temporary session token via the `POST /login` endpoint.
2. **Using the token:** Include the session token in the `Authorization` header of all subsequent API requests.

<Note>
  Session tokens expire after one hour. When they expire, refresh them. See the Token expiration section below for handling token refresh automatically.
</Note>

## Prerequisites

Before you start, make sure you have the following:

* **Static API Key:** Your static API key provided by Quivo. You can retrieve it from the Quivo Dashboard
* **Username:** Your Quivo account username
* **Password:** Your Quivo account password

<Note>
  All API examples in this reference use `${BASE_URL}` as a placeholder. Replace it with the correct base URL configured for the correct environment. For more information see [Environments page](/api-reference/environments).
</Note>

## Obtain a session token

Exchange your credentials for a session token via the `POST /login` endpoint. Replace the placeholders with your actual data.

<Tabs>
  <Tab title="Request">
    Use this request to exchange your credentials for a session token:

    ```bash theme={null}
    curl -X POST "${BASE_URL}/login" \
      -H "Content-Type: application/json" \
      -H "X-Api-Key: <YOUR_STATIC_API_KEY>" \
      -d '{
        "username": "<YOUR_USERNAME>",
        "password": "<YOUR_PASSWORD>"
      }'
    ```
  </Tab>

  <Tab title="Response">
    A successful request returns a `200 OK` status code. The API returns a token string in the response:

    ```json theme={null}
    {
      "Token": "<YOUR_SESSION_TOKEN>"
    }
    ```
  </Tab>
</Tabs>

## Use the token in requests

Include the token in the `Authorization` header of all API requests. You must also include your API key in the `X-Api-Key` header. The following example shows how to make an authenticated request using the [`GET /orders endpoint`](/api-reference/#tag/orders). Replace the placeholders with your actual data.

<Tabs>
  <Tab title="Request">
    Use this request example to make an authenticated API call with your session token:

    ```bash theme={null}
    curl -X GET "${BASE_URL}/orders" \
      -H "X-Api-Key: <YOUR_STATIC_API_KEY>" \
      -H "Authorization: <YOUR_SESSION_TOKEN>"
    ```
  </Tab>

  <Tab title="Response">
    A successful authenticated request returns the requested data. If authentication fails, you'll receive a `401 Unauthorized` error.

    ```json theme={null}
    {
      "orderId": <YOUR_ORDER_ID>,
      "orderStatus": "<ORDER_STATUS>"
    }
    ```
  </Tab>
</Tabs>

## Token expiration

Session tokens expire after 1 hour. When a token expires, you receive a `401 Unauthorized` error response.

### Handling token expiration

When you receive a 401 error, your integration should automatically:

1. **Retry authentication:** Call the `POST /login` endpoint again to obtain a new token
2. **Retry the original request:** Use the new token to retry the request that failed

<Tip>
  Implement automatic token refresh in your integration to handle expiration seamlessly. Monitor API responses for `401 Unauthorized` errors and trigger re-authentication as needed.
</Tip>

## Where to go next

Now that you understand authentication, continue with these guides:

<CardGroup cols={2}>
  <Card title="Create a Fulfillment Order" icon="shopping-cart" href="/docs/quickstart/create-order">
    Start the fulfillment process by creating orders for your customers.
  </Card>

  <Card title="Send Inventory" icon="warehouse" href="/docs/quickstart/send-inventory">
    Send your products to Quivo warehouses to make them available for fulfillment.
  </Card>
</CardGroup>