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

# Authentication

Authenticating with the tipee API involves generating an API key through the tipee application interface and then using that key in your API requests.

## Setup and API key generation

Before making API calls, you need to configure API access within your tipee instance and generate an API key. This setup process requires administrative privileges in tipee.

<Steps>
  <Step title="Enable API Access">
    An administrator must first enable API access for the specific tipee instance.
  </Step>

  <Step title="Create an Integration">
    Create a dedicated integration principal within the tipee application. This integration acts as the identity for your API interactions. More information [here](https://help.tipee.net/en/articles/440079)
  </Step>

  <Step title="Assign Roles/Permissions">
    Assign appropriate roles and permissions to the newly created integration. Without assigned permissions, the integration will not have the necessary access to read or modify any resource via the API, even if authentication is successful.
  </Step>

  <Step title="Generate API Key">
    Generate an API key specifically for this integration. This key will be used to authenticate all subsequent API requests made by this integration.
  </Step>
</Steps>

<Info>Detailed, step-by-step instructions for enabling API access, creating integrations, and managing API keys are available in the tipee Help Center. This process must be performed by a user with administrative access.</Info>

<Warning>Treat your API key like a password — keep it confidential and secure. Do not embed it directly in client-side code or commit it to version control.</Warning>

## Making authenticated requests

Once you have a valid API key, you must include it in the `Authorization` header for every request, using the `Bearer` authentication scheme:

```
Authorization: Bearer <YOUR_API_KEY>
```

Requests without a valid `Authorization` header or with an incorrect/inactive key will be rejected.

## Authentication-related errors

| Code  | Name         | Cause                                                                                                                 |
| ----- | ------------ | --------------------------------------------------------------------------------------------------------------------- |
| `401` | Unauthorized | The API key is missing, invalid, or expired                                                                           |
| `403` | Forbidden    | The API key is valid, but the associated integration does not have the necessary permissions for the requested action |

<Card title="Error Handling" icon="bomb" href="/guides-and-resources/error-handling">
  See the full list of error codes and recommended actions.
</Card>