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

# Auth Profiles

Create and manage browser auth profiles for private page capture.

Auth profiles store browser authentication state for capture requests. They are useful for dashboards, internal tools, and staging apps that require login.

## Endpoints

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/v1/auth-profiles` | List auth profiles. |
| `POST` | `/v1/auth-profiles` | Create an auth profile. |
| `PATCH` | `/v1/auth-profiles/{id}` | Update an auth profile. |
| `POST` | `/v1/auth-profiles/{id}/test` | Test profile against a URL. |
| `DELETE` | `/v1/auth-profiles/{id}` | Delete a profile. |

## Create with cookie header

```bash
curl -X POST "https://screenframed.com/v1/auth-profiles" \
  -H "Authorization: Bearer $SCREENFRAMED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production dashboard",
    "domain": "app.example.com",
    "cookie_header": "session=..."
  }'
```

## Create with browser storage state

For most real workflows, use the CLI:

```bash
screenframed auth login --url https://app.example.com/login --project prj_...
```

The CLI captures cookies and localStorage from a real browser session and sends them to the auth profile API.

## Use in a capture

```json
{
  "url": "https://app.example.com/dashboard",
  "auth_profile_id": "ap_01K...",
  "project_id": "prj_01K..."
}
```

## Test a profile

```bash
curl -X POST "https://screenframed.com/v1/auth-profiles/ap_01K.../test" \
  -H "Authorization: Bearer $SCREENFRAMED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://app.example.com/dashboard" }'
```

## Limits and matching

- Auth profiles are matched by domain.
- Profiles can be scoped to a project.
- Cookie and storage inputs are normalized and size-limited.
- Delete profiles when credentials no longer need to be used for captures.

Auth profile material is stored server-side and referenced by id in capture requests. Treat profile ids as sensitive operational handles.

` GET /v1/auth-profiles `

List auth profiles

## Servers

- ` https://screenframed.com ` — Production

## Authentication

The operation accepts these alternatives. Schemes within one alternative are required together.

### Alternative 1

- ` bearerAuth `: ` http `

  - HTTP scheme: ` bearer `

  - ScreenFramed API key, such as `sf_live_...`.

## Parameters

### ` project_id ` (query, optional)

- ` value `: type ` string `

  - pattern: ` "^prj_[A-Z0-9]{26}$" `

## Responses

### ` 200 ` — Auth profile list

Content type: ` application/json `

- ` value `: type ` object `

  - ` profiles `: type ` array `

    - ` array item `: type ` object `

      - ` id `: type ` string `

        - pattern: ` "^ap_" `

      - ` project_id `: type ` string `; nullable

      - ` name `: type ` string `

      - ` domain `: type ` string `

      - ` cookie_count `: type ` integer `

      - ` status `: type ` string `

      - ` last_used_at `: type ` string `; nullable

      - ` created_at `: type ` string `

      - ` updated_at `: type ` string `

### ` 401 ` — Error response

Content type: ` application/json `

- ` value `: type ` object `

  - Required fields: ` error `

  - ` error `: type ` object `

    - Required fields: ` code `, ` message `

    - ` code `: type ` string `

    - ` message `: type ` string `

    - ` details `: type ` object `

    - ` retry_after `: type ` integer `

### ` 403 ` — Error response

Content type: ` application/json `

- ` value `: type ` object `

  - Required fields: ` error `

  - ` error `: type ` object `

    - Required fields: ` code `, ` message `

    - ` code `: type ` string `

    - ` message `: type ` string `

    - ` details `: type ` object `

    - ` retry_after `: type ` integer `

## Request examples

### cURL

```curl
curl -X GET 'https://screenframed.com/v1/auth-profiles' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://screenframed.com/v1/auth-profiles', {
  method: 'GET',
  headers: {
      "Authorization": "Bearer YOUR_API_TOKEN"
  }
});

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

### Python

```python
import requests

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN'
}

response = requests.get('https://screenframed.com/v1/auth-profiles', headers=headers)
print(response.json())
```