# Authentication

### Introduction

Authentication for the Gangmates API is based on bearer tokens. Each company is issued a unique API token that must be included in the header of each request to authenticate and authorize access to the API endpoints.

### Obtaining an API Token

To obtain an API token, contact your administrator. The token will be provided and must be kept secure.

### Using the API Token

Include the API token in the `Authorization` header of your HTTP requests. The format should be as follows:

```css
Authorization: Bearer {your_api_token}
```

#### Example Request

```http
GET /api/paystubs HTTP/1.1
Host: stage.gangmates.com
Authorization: Bearer your_api_token
```

### Managing API Tokens

API tokens can be managed through the Gangmates UI. Each company can generate, regenerate, and invalidate their API token.

#### Generating a New Token

1. Log in to the Gangmates UI.
2. Navigate to the "Security" tab then select "API" from the drop down.
3. Click the "Generate Token" button.
4. The new token will be generated. Copy and store it securely.

#### Invalidating a Token

1. Log in to the Gangmates UI.
2. Navigate to the "Security" tab then select "API" from the drop down.
3. Click the "Invalidate Token" button.
4. The token will be invalidated, and any further requests using that token will be unauthorized.

#### Token lifecycle

* **Sliding expiry:** tokens expire **30 days** from last use. Every successful call resets the expiry to 30 days from "now".
* **Inactivity revocation:** tokens unused for **30 days** are revoked and will return `401 Token expired`.
* **Scopes:** tokens may carry scopes that map to route names. If a route isn’t allowed by your scopes, you’ll receive `403`.
  * Special scope: `all` grants access to all scoped endpoints.

> **Tip:** Rotate and store tokens securely. Revoke compromised tokens from **Security → API** in the UI.

### Error Handling

If an invalid or missing token is provided, the following response will be returned:

```json
{
    "error": "Unauthorized"
}
```

Ensure that your token is correctly included in the `Authorization` header of each request.

### Contact

For any questions or support, please contact our support team at <support@gangmates.com>.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.gangmates.com/api-documentation/api-overview/authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.