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

# Authentication

> How to authenticate with the Alana Shopping B2B API using API keys or session tokens.

## Authentication methods

The Alana Shopping B2B API supports two authentication methods depending on your use case.

### API Keys (recommended for integrations)

API keys are the recommended way to authenticate programmatic access. Each key is scoped to a workspace and can have granular permissions.

```bash theme={null}
curl -H "Authorization: Bearer sk_live_abc123..." \
  https://app.alana.shopping/api/workspace/{workspaceId}/brands
```

Key characteristics:

* Prefixed with `sk_live_` for production keys
* Shown only once at creation — store securely
* Can be revoked instantly without affecting other keys
* Track `last_used_at` for audit purposes
* Expire based on your workspace security policy

### Session auth (browser/dashboard)

When using the dashboard, authentication is handled via Supabase Auth sessions. This method supports email/password, magic links, and OAuth providers (Google, GitHub).

Session tokens are managed automatically by the browser client and are not meant for API integrations.

## Workspace context

Every API request operates within a workspace context. The workspace ID is part of the URL path:

```
/api/workspace/{workspaceId}/...
```

Your API key must belong to the specified workspace. Requests to a workspace where the key doesn't have membership will return `403 Forbidden`.

## Role-based access

API keys inherit the permissions of the user who created them. The role hierarchy controls what operations are allowed:

| Role       | Level | Capabilities                                                 |
| ---------- | ----- | ------------------------------------------------------------ |
| **Owner**  | 4     | Full control — billing, delete workspace, transfer ownership |
| **Admin**  | 3     | Manage members, brands, catalogs, API keys                   |
| **Editor** | 2     | Create and modify products, catalogs                         |
| **Viewer** | 1     | Read-only access to all resources                            |

<Info>
  API keys created by an admin cannot perform owner-level operations like deleting the workspace or transferring ownership.
</Info>

## Security best practices

<AccordionGroup>
  <Accordion title="Rotate keys regularly">
    Create new keys and revoke old ones on a regular schedule. Use the `expiresAt` field when creating keys to enforce automatic expiration.
  </Accordion>

  <Accordion title="Use minimum permissions">
    Create separate keys for different integrations with only the permissions each needs.
  </Accordion>

  <Accordion title="Never expose keys in client-side code">
    API keys should only be used server-side. Never include them in browser JavaScript, mobile apps, or public repositories.
  </Accordion>

  <Accordion title="Monitor usage">
    Check `last_used_at` timestamps and audit logs regularly. Revoke any key that shows unexpected activity.
  </Accordion>
</AccordionGroup>