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

# Sessions

> Create session tokens for embedded applications

Session tokens are used to authenticate embedded applications and third-party integrations.

## Create Session (OAuth2)

<Card title="POST /api/v1/sessions" icon="key">
  Used by third-party backend services using Telzino Account API Keys.
</Card>

### Request Body

| Field        | Type          | Required | Description                       |
| ------------ | ------------- | -------- | --------------------------------- |
| `profile_id` | string (UUID) | Yes      | Configuration profile ID          |
| `user_id`    | string        | No       | Optional external user identifier |

### Example Request

```bash theme={null}
curl -X POST "https://api.telzino.com/api/v1/sessions" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_id": "123e4567-e89b-12d3-a456-426614174000",
    "user_id": "1234-5678"
  }'
```

### Example Response

```json theme={null}
{
  "token": "abc123xyz",
  "expires_at": "2025-07-02T18:30:00Z"
}
```

***

## Create Session (NetSapiens)

<Card title="POST /api/v1/sessions/netsapiens" icon="phone">
  Used by NetSapiens frontend JavaScript for direct integration.
</Card>

### Headers

| Header         | Type   | Required | Description                     |
| -------------- | ------ | -------- | ------------------------------- |
| `X-NS-Api-Key` | string | Yes      | NetSapiens API token from OAuth |

### Request Body

| Field        | Type          | Required | Description                       |
| ------------ | ------------- | -------- | --------------------------------- |
| `profile_id` | string (UUID) | Yes      | Configuration profile ID          |
| `claim_id`   | string (UUID) | Yes      | NetSapiens user base claim ID     |
| `user_id`    | string        | No       | Optional external user identifier |

### Example Request

```bash theme={null}
curl -X POST "https://api.telzino.com/api/v1/sessions/netsapiens" \
  -H "X-NS-Api-Key: ns_api_token_from_netsapiens_oauth" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_id": "123e4567-e89b-12d3-a456-426614174000",
    "claim_id": "9f14c1a4-02f0-4ad0-b5f4-08c1f8f9b3a2"
  }'
```

### Example Response

```json theme={null}
{
  "token": "abc123xyz",
  "expires_at": "2025-07-02T18:30:00Z"
}
```

### Error Responses

| Code | Description                                     |
| ---- | ----------------------------------------------- |
| 400  | Bad request - missing or invalid fields         |
| 401  | Unauthorized - invalid API key or authorization |
| 404  | Profile or claim not found                      |
| 500  | Internal server error                           |

**400 Error Example (both endpoints):**

```json theme={null}
{
  "error": "Invalid request data",
  "details": [
    {
      "code": "invalid_string",
      "validation": "uuid",
      "message": "profile_id must be a valid UUID",
      "path": ["profile_id"]
    }
  ]
}
```