![Secure](/assets/secure.6c9e55b722a50a2c0f86fa0e0796fe5ae5abd9dfc0bc7c425d887b199c732727.9c1bb791.png)

# Authentication

Elevate IQ APIs use Bearer authentication (also called token authentication) - this is an HTTP authentication scheme that uses security tokens called bearer tokens.

## Overview

All requests to the Elevate REST APIs must be authenticated and include a valid access token in the Authorization header.

## Prerequisites

An API user account is required to access the APIs. This can be set up on Elevate in the manage users/roles sections.

**Important:** The permissions set up on the Elevate UI will apply to API calls as well. For example, if a user can only access customers belonging to a single contract owner on the UI, that user will have the same restriction when calling via the APIs.

## Obtaining an Access Token

To authenticate with the Elevate API, you need to obtain a bearer token from your API credentials.

### Authentication Request

Contact Elevate support to obtain your API credentials:

- API Username
- API Password
- API Endpoint URL


### Using the Token

Once you have your bearer token, include it in the Authorization header of all API requests:


```
Authorization: Bearer YOUR_ACCESS_TOKEN
```

### Example Request


```bash
curl -X GET "https://api.elevateiq.com/v2/customers?page=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"
```

## Token Best Practices

1. **Secure Storage** - Never store tokens in plain text or commit them to source control
2. **Token Expiry** - Be prepared to handle token expiration and refresh as needed
3. **HTTPS Only** - Always use HTTPS when transmitting tokens
4. **Minimal Permissions** - Request only the permissions your integration needs
5. **Token Rotation** - Rotate credentials periodically for security


## Managing Users and Roles

The Authentication REST API provides endpoints for managing users and roles:

- `GET /users` - Retrieve Elevate users
- `POST /users` - Create new Elevate users
- `PATCH /users` - Update existing users
- `GET /user-roles` - Retrieve available user roles (read-only)


## Security Considerations

- Access tokens should be treated as sensitive credentials
- Implement proper error handling for authentication failures (401 responses)
- Use secure communication channels (HTTPS/TLS)
- Monitor and log authentication attempts for security purposes
- Follow the principle of least privilege when assigning user permissions


## Troubleshooting

### 401 Unauthorized Error

If you receive a 401 error:

- Verify your token is valid and not expired
- Check that the user account is still active
- Ensure the Authorization header is correctly formatted


### 403 Forbidden Error

If you receive a 403 error:

- Verify the user has permission to access the requested resource
- Check that the correct permissions are assigned in Elevate UI
- Contact your administrator to adjust user permissions if needed


## Need Help?

For assistance with authentication:

- Review the [API Reference](/api) for authentication endpoints
- Contact [Elevate support](/pages/contact) for help