# Connect via API

AccessIQ provides a REST API that lets you integrate identity and access management into your own applications and workflows.

## Base URL

All API requests use your tenant-specific base URL:

```
https://<your-tenant>.accessiq.app/api/v1
```

## Authentication

There are two ways to authenticate API requests:

| Method             | Use case                      | Header                                 |
| ------------------ | ----------------------------- | -------------------------------------- |
| API Key            | Server-to-server integrations | `Authorization: Bearer <api-key>`      |
| OAuth Access Token | Acting on behalf of a user    | `Authorization: Bearer <access-token>` |

See [API Key Management](/accessiq-docs/applications-and-api/api-keys.md) for creating API keys, or [OAuth Apps](/accessiq-docs/applications-and-api/oauth-apps.md) for obtaining user access tokens.

## Common API Endpoints

| Endpoint                      | Method | Description                     |
| ----------------------------- | ------ | ------------------------------- |
| `/users`                      | GET    | List users in your tenant       |
| `/users/{id}`                 | GET    | Get a specific user             |
| `/users`                      | POST   | Create a new user               |
| `/users/{id}`                 | PATCH  | Update a user                   |
| `/organizations`              | GET    | List organizations              |
| `/organizations/{id}/members` | GET    | List members of an organization |
| `/roles`                      | GET    | List available roles            |
| `/applications`               | GET    | List registered applications    |
| `/audit/events`               | GET    | Query audit log events          |

## Request Format

* Send request bodies as JSON with `Content-Type: application/json`.
* Use query parameters for filtering and pagination.

### Pagination

List endpoints support pagination:

| Parameter | Description                                       | Default |
| --------- | ------------------------------------------------- | ------- |
| `page`    | Page number (starting at 0)                       | 0       |
| `size`    | Number of items per page                          | 20      |
| `sort`    | Sort field and direction (e.g., `createdAt,desc`) | Varies  |

## Response Format

All responses are JSON. Successful responses return the data directly or in a paginated wrapper:

```json
{
  "content": [...],
  "page": 0,
  "size": 20,
  "totalElements": 57,
  "totalPages": 3
}
```

Error responses include a message:

```json
{
  "status": 400,
  "error": "Bad Request",
  "message": "Email is required"
}
```

## Rate Limits

API requests are rate-limited per tenant. If you exceed the limit, the API returns `429 Too Many Requests`. The response headers indicate when you can retry:

| Header                  | Description                              |
| ----------------------- | ---------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests per window              |
| `X-RateLimit-Remaining` | Requests remaining in the current window |
| `Retry-After`           | Seconds to wait before retrying          |

## Next Steps

* [Register an OAuth App](/accessiq-docs/applications-and-api/oauth-apps.md) to authenticate users
* [Create an API Key](/accessiq-docs/applications-and-api/api-keys.md) for server-side access
* [View Audit Logs](/accessiq-docs/audit-and-compliance/audit-logs.md) to monitor API activity


---

# 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://accessiq.gitbook.io/accessiq-docs/applications-and-api/connect-via-api.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.