# Authentication

The Apiera API uses OAuth 2.0 for authentication. All requests must include a valid access token and organization context.

## Overview

To access the API, you need:

1. **Client credentials** (client ID and secret)
2. **Organization ID**
3. **Access token** (obtained using your credentials)


## Getting Your Credentials

1. Log in to your Apiera Dashboard
2. Navigate to **Settings** → **API Access**
3. Create a new API client
4. Save your **Client ID**, **Client Secret**, and **Organization ID**


Store your client secret securely. It cannot be retrieved after creation.

## Obtaining an Access Token

Request an access token using your client credentials:


```http
POST /oauth/token HTTP/1.1
Host: auth.apiera.io
Content-Type: application/json

{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "audience": "https://api.apiera.io",
  "grant_type": "client_credentials",
  "organization": "org_YOUR_ORG_ID"
}
```

**Response:**


```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 86400
}
```

## Making Authenticated Requests

Include the access token in the `Authorization` header:


```http
GET /v1/products HTTP/1.1
Host: api.apiera.io
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json
```

## Token Expiration

Access tokens expire after 24 hours. When a token expires:

1. Request a new token using your client credentials
2. Update your application to use the new token
3. Retry the failed request


**Expired token response:**


```json
{
  "error": "invalid_token",
  "message": "Token has expired"
}
```

## Permissions

Access tokens include permissions based on your organization role:

- **read** - View all resources
- **write** - Create and modify resources
- **delete** - Remove resources
- **admin** - Manage organization settings


## Best Practices

**Cache tokens**
Reuse tokens until they expire instead of requesting new ones for each request.

**Secure credentials**
Store client secrets in environment variables, never in code.

**Separate environments**
Use different credentials for development, staging, and production.

**Handle expiration**
Implement automatic token refresh before expiration.

## Common Errors

**401 Unauthorized** - Invalid or expired token
**403 Forbidden** - Insufficient permissions for the requested operation
**400 Bad Request** - Missing or invalid organization ID