# Authentication

> Authenticate every request with an API key passed as a Bearer token.

PicX Studio uses API key authentication. Every request must include your key in the Authorization header as a Bearer token. Keys are scoped to specific operations and can be revoked at any time.

## Authorization header

```http
Authorization: Bearer pxsk_your_api_key_here
```

## Using your key

1. **Create a key**

   In the API dashboard, create a new key and select its scopes. Keys are created and managed through the dashboard API — see Developer Tools → API Keys.

2. **Copy it once**

   The full key starts with pxsk_ and is shown only once at creation. Store it in a secret manager or an environment variable.

3. **Send it with every request**

   Add the Authorization: Bearer pxsk_… header to each call. The key identifies your account and is used for billing and rate limiting.

> [!WARNING]
> Never expose API keys in client-side code, public repositories, or browser network requests. Keep them server-side and load them from environment variables or a secret manager.

Scopes restrict what a key can do. Request only the scopes an integration actually needs.

## Available scopes

```
images:generate   Generate images from text prompts
images:edit       Edit existing images with instructions
videos:generate   Generate videos from text or images
uploads:write     Upload files to managed assets for image/video inputs
audio:generate    Generate audio and music
agent:run         Run AI agent workflows
```

> [!NOTE]
> API keys (pxsk_…) are for programmatic access from servers, scripts, and apps. They are separate from the browser session (JWT) the dashboard uses.

## Verify your key

**JavaScript SDK**

```bash
npm install picx-ai
```

```js
import { PicX } from "picx-ai";

const picx = new PicX(process.env.PICX_API_KEY);

const me = await picx.account.me();
console.log(me.name, me.email);
console.log("Credits:", me.credits.balance);
```

**Python SDK**

```bash
pip install picx-ai
```

```python
import os
from picx import PicX

picx = PicX(os.environ["PICX_API_KEY"])

me = picx.account.me()
print(me.name, me.email)
print("Credits:", me.credits["balance"])
```

**curl**

```bash
curl https://api.picxstudio.com/v1/account/me \
  -H "Authorization: Bearer pxsk_your_key"
```

**Response**

```json
{
  "id": "1c4d3574-883c-4cd8-85f5-7090bf686d64",
  "email": "you@example.com",
  "name": "Your Name",
  "is_active": true,
  "credits": {
    "balance": 2164,
    "total_earned": 17100,
    "total_used": 6533
  }
}
```

## FAQ

### How do I authenticate a request?

Add an `Authorization: Bearer pxsk_your_api_key_here` header to every request. The key identifies your account and is used for both billing and rate limiting.

### Where do I get an API key?

Create one from the API dashboard, under Developer Tools → API Keys. The full key is shown only once, at creation — store it in a secret manager or environment variable immediately.

### Can I limit what a key is allowed to do?

Yes — keys are scoped. Available scopes are `images:generate`, `images:edit`, `videos:generate`, `uploads:write`, `audio:generate`, and `agent:run`. Request only the scopes an integration actually needs.

### Is it safe to use my API key in client-side/browser code?

No — never expose API keys in client-side code, public repositories, or browser network requests. Keep them server-side, loaded from environment variables or a secret manager.

### How do I check that my key works?

Call `GET /v1/account/me` with the key — a successful response returns your account details and current credit balance. See "Verify your key" above.