> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/grokability/snipe-it/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Learn how to authenticate with the Snipe-IT API using personal access tokens

The Snipe-IT API uses **Laravel Passport** for authentication via personal access tokens. All API requests must include a valid bearer token in the Authorization header.

## Base URL

All API endpoints are prefixed with `/api/v1`:

```
https://your-snipe-it-instance.com/api/v1
```

## Authentication Methods

### Personal Access Tokens

Snipe-IT uses OAuth 2.0 personal access tokens for API authentication. These tokens allow you to authenticate API requests without exposing your password.

#### Generating a Token

You can generate a personal access token using the API itself (requires initial authentication) or through the web interface.

**Via API:**

<CodeGroup>
  ```bash Create Token theme={null}
  curl -X POST https://your-snipe-it-instance.com/api/v1/account/personal-access-tokens \
    -H "Authorization: Bearer YOUR_EXISTING_TOKEN" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{
      "name": "My API Token"
    }'
  ```

  ```json Response theme={null}
  {
    "status": "success",
    "messages": "Personal API key 'My API Token' created successfully.",
    "payload": {
      "id": "9a8f7e6d-5c4b-3a2b-1c0d-9e8f7a6b5c4d",
      "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
      "name": "My API Token"
    }
  }
  ```
</CodeGroup>

<Warning>
  Save the token immediately! For security reasons, the full token is only displayed once during creation. If you lose it, you'll need to generate a new one.
</Warning>

#### Listing Your Tokens

Retrieve all active personal access tokens for the authenticated user:

<CodeGroup>
  ```bash List Tokens theme={null}
  curl https://your-snipe-it-instance.com/api/v1/account/personal-access-tokens \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Accept: application/json"
  ```

  ```json Response theme={null}
  {
    "status": "success",
    "payload": [
      {
        "id": "9a8f7e6d-5c4b-3a2b-1c0d-9e8f7a6b5c4d",
        "user_id": 1,
        "client_id": "9a8f7e6d-5c4b-3a2b-1c0d-9e8f7a6b5c4d",
        "name": "My API Token",
        "scopes": [],
        "revoked": false,
        "created_at": "2024-03-15T10:30:00.000000Z",
        "updated_at": "2024-03-15T10:30:00.000000Z",
        "expires_at": "2039-03-15T10:30:00.000000Z"
      }
    ]
  }
  ```
</CodeGroup>

#### Deleting a Token

Revoke a personal access token when it's no longer needed:

<CodeGroup>
  ```bash Delete Token theme={null}
  curl -X DELETE https://your-snipe-it-instance.com/api/v1/account/personal-access-tokens/{tokenId} \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Accept: application/json"
  ```
</CodeGroup>

<ParamField path="tokenId" type="string" required>
  The UUID of the token to delete (e.g., `9a8f7e6d-5c4b-3a2b-1c0d-9e8f7a6b5c4d`)
</ParamField>

A successful deletion returns HTTP status `204 No Content`.

## Using Your Token

Include your personal access token in the `Authorization` header of every API request using the Bearer authentication scheme:

```bash theme={null}
Authorization: Bearer YOUR_ACCESS_TOKEN
```

### Example Request

<CodeGroup>
  ```bash Get Assets theme={null}
  curl https://your-snipe-it-instance.com/api/v1/hardware \
    -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..." \
    -H "Accept: application/json"
  ```

  ```python Python theme={null}
  import requests

  headers = {
      'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...',
      'Accept': 'application/json',
  }

  response = requests.get(
      'https://your-snipe-it-instance.com/api/v1/hardware',
      headers=headers
  )

  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://your-snipe-it-instance.com/api/v1/hardware',
    {
      headers: {
        'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...',
        'Accept': 'application/json',
      },
    }
  );

  const data = await response.json();
  console.log(data);
  ```

  ```php PHP theme={null}
  <?php
  $client = new GuzzleHttp\Client();

  $response = $client->get('https://your-snipe-it-instance.com/api/v1/hardware', [
      'headers' => [
          'Authorization' => 'Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...',
          'Accept' => 'application/json',
      ],
  ]);

  $data = json_decode($response->getBody(), true);
  print_r($data);
  ```
</CodeGroup>

## Token Expiration

By default, personal access tokens expire after **15 years** from creation. You can customize this expiration period using the `API_TOKEN_EXPIRATION_YEARS` environment variable:

```bash .env theme={null}
API_TOKEN_EXPIRATION_YEARS=15
```

## Content Type Headers

<Note>
  Always include the `Accept: application/json` header in your requests to ensure you receive JSON responses.
</Note>

For `POST`, `PUT`, and `PATCH` requests, also include:

```bash theme={null}
Content-Type: application/json
```

## Authentication Errors

### Unauthenticated (401)

Returned when no valid token is provided:

```json theme={null}
{
  "status": "error",
  "message": "Unauthenticated.",
  "payload": null
}
```

### Forbidden (403)

Returned when the authenticated user lacks permissions:

```json theme={null}
{
  "status": "error",
  "message": "Insufficient permissions.",
  "payload": null
}
```

### Invalid Token

If your token is malformed or expired:

```json theme={null}
{
  "status": "error",
  "message": "The token is invalid or has expired.",
  "payload": null
}
```

## Security Best Practices

<AccordionGroup>
  <Accordion title="Store tokens securely">
    * Never commit tokens to version control
    * Use environment variables or secure secret management systems
    * Treat tokens like passwords
  </Accordion>

  <Accordion title="Use HTTPS">
    Always use HTTPS to prevent token interception. Configure your Snipe-IT instance with:

    ```bash .env theme={null}
    APP_FORCE_TLS=true
    SECURE_COOKIES=true
    ```
  </Accordion>

  <Accordion title="Rotate tokens regularly">
    Periodically delete old tokens and generate new ones, especially:

    * When team members leave
    * If you suspect a token has been compromised
    * As part of regular security maintenance
  </Accordion>

  <Accordion title="Use descriptive names">
    Name your tokens based on their purpose or application:

    * "Production Monitoring Script"
    * "Mobile App Integration"
    * "Backup Automation"
  </Accordion>

  <Accordion title="Limit token scope">
    Create separate tokens for different applications or purposes rather than sharing a single token across multiple systems.
  </Accordion>
</AccordionGroup>

## Testing Authentication

Verify your authentication setup by retrieving your user profile:

<CodeGroup>
  ```bash Test Authentication theme={null}
  curl https://your-snipe-it-instance.com/api/v1/users/me \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Accept: application/json"
  ```

  ```json Response theme={null}
  {
    "id": 1,
    "name": "Admin User",
    "first_name": "Admin",
    "last_name": "User",
    "username": "admin",
    "employee_num": null,
    "email": "admin@example.com",
    "permissions": {
      "superuser": 1
    },
    "created_at": {
      "datetime": "2024-01-15 10:30:00",
      "formatted": "January 15, 2024 10:30 AM"
    }
  }
  ```
</CodeGroup>

<Check>
  If you receive your user details, your authentication is working correctly!
</Check>

## Next Steps

<CardGroup cols={2}>
  <Card title="Rate Limits" icon="gauge-high" href="/api/rate-limits">
    Learn about API rate limiting and quotas
  </Card>

  <Card title="Assets" icon="laptop" href="/api/assets">
    Start working with asset endpoints
  </Card>
</CardGroup>