# Authentication

> The headers every request carries, the two kinds of credential, and the scopes that decide what each one can do.

## Required headers

Every GraphQL request carries a bearer token. Item queries also name the index and the shopper. Other pages link here rather than repeat this table.

| Header | Value | Needed on |
|--------|-------|-----------|
| `Authorization` | `Bearer <token>`: a secret API key or a session access token | Every request |
| `Solenya-Index-UUID` | The index to query | `items` and `experiments` queries |
| `Solenya-User-UUID` | A UUID for the shopper. See [Shopper IDs](https://solenya.ai/docs/search.md#shopper-ids). | `items` queries |
| `Content-Type` | `application/json` | Every GraphQL `POST` |

Event tracking is different: it sends its token as a form field, not a header. See [Event tracking](https://solenya.ai/docs/track.md#authentication).

## Which credential to use

Every Solenya credential is a JWT sent as a bearer token.

| | Secret API key | Publishable key | Session token |
|---|---|---|---|
| For | Your backend | Browsers and apps | People on your team |
| Can | Query items, change its index, manage experiments, read shopper events | Send tracking events for one index | Whatever the person's scopes allow |
| Keep secret | Yes. Never ship it to a client. | No. It is safe in client code. | Yes |
| Lifetime | 365 days by default | 3650 days by default | 2 hours, renewed with a 90-day refresh token |

Item queries need a secret key, so they can't be sent straight from a shopper's browser on your site, and the API accepts cross-site browser requests only from a fixed list of origins that Solenya maintains. Send them from your backend with a secret key. [Errors and limits](https://solenya.ai/docs/errors.md#calling-from-a-browser) explains what does work in the browser.

## API keys

| | Secret API key | Publishable key |
|---|---|---|
| Scopes | `index:read:<index_uuid>` `index:write:<index_uuid>` `user:read:*` `user:write:*` | `events:write:<index_uuid>` |
| Who can create it | Someone with `customer:write:<customer_uuid>` | Someone with `index:write:<index_uuid>` |
| Endpoint | `POST /v1/auth/keys/api-key` | `POST /v1/auth/keys/publishable-key` |

Create keys in the Console under **Developer tools → Settings → Tokens**, or with the endpoints above and a session access token. Both take the same form fields: `index_uuid`, `name`, and `expires_in_days` from 1 to 3650.

```bash
curl -X POST https://api.solenya.ai/v1/auth/keys/api-key \
  -H "Authorization: Bearer <access_token>" \
  -d "index_uuid=<index_uuid>" \
  -d "name=Production server key" \
  -d "expires_in_days=365"
```

The response holds the key itself. Solenya keeps only its metadata, so copy the key now:

```json
{
  "key": "<api_key>",
  "name": "Production server key",
  "customer_uuid": "<customer_uuid>",
  "index_uuid": "<index_uuid>",
  "scopes": "index:write:<index_uuid> index:read:<index_uuid> user:write:* user:read:*",
  "expires_in_days": 365,
  "key_type": "api_key"
}
```

| To | Call | Needs |
|----|------|-------|
| List keys | `GET /v1/auth/keys`, with `?include_revoked=true` to include revoked ones | `customer:read` |
| Revoke a key | `DELETE /v1/auth/keys/{jti}`, using the `jti` from the list | `customer:write` |

A revoked key is rejected from then on. Revoking a key twice is not an error.

## Sign-in and session tokens

Team members sign in to the Console with Google or Microsoft. Signing in gives them an access token, valid for 2 hours, and a refresh token, valid for 90 days.

To renew, exchange the refresh token for a new pair. Each refresh token works once; the response carries its replacement.

```bash
curl -X POST https://api.solenya.ai/v1/auth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token&refresh_token=<refresh_token>"
```

```json
{
  "access_token": "<access_token>",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "<new_refresh_token>"
}
```

Other endpoints under `https://api.solenya.ai/v1/auth`:

| Endpoint | Does | Needs |
|----------|------|-------|
| `POST /revoke` | Revokes one refresh token (`token`, optional `token_type_hint`) | `user:write` on your own account user |
| `POST /revoke-all` | Revokes every refresh token of one team member (`subject_uuid`) | `customer:write` |
| `POST /introspect` | Says whether a token is active and returns its claims (RFC 7662) | Nothing for your own token; `user:read:<their uuid>` for someone else's |
| `GET /memberships` | Lists the customer accounts you belong to | Any valid access token |
| `POST /switch-tenant` | Returns a token pair for another customer account you belong to (`customer_uuid`) | Membership of that account |

## Scopes

A scope has the form `resource:action:identifier`, and a token carries a space-separated list of them.

| Part | Values |
|------|--------|
| `resource` | `customer`, `index`, `feed`, `user`, `items`, `item_batch`, `events`, `sizing` |
| `action` | `read` or `write`. They are separate: `write` does not include `read`. |
| `identifier` | `*` for all, or one customer, index or user UUID |

Each request is checked against the exact resource it touches. `customer:read:<customer_uuid>` does not let a token query items; that needs `index:read`.

| Scope | Lets a token |
|-------|--------------|
| `index:read:<index_uuid>` | Query items from that index |
| `index:write:<index_uuid>` | Change and delete that index, and create and run its experiments |
| `index:write:*` | All of the above for every index, and create new indexes |
| `events:write:<index_uuid>` | Send tracking events for that index |
| `user:read:*` | Read shopper records and their recent events |
| `customer:read:<customer_uuid>` | List feeds, API keys and team members |
| `customer:write:<customer_uuid>` | Add and delete feeds; create and revoke API keys; add team members, change their scopes and disable them; end a team member's sessions; change account settings |

API keys get the fixed scopes in the [API keys](https://solenya.ai/docs/auth.md#api-keys) table. Team members get theirs from an admin, as below.

## Account users

Account users are the people on your team who can sign in to the Console. Each has a list of scopes. Listing the team needs `customer:read`; adding a team member or changing their scopes needs `customer:write`. Disabling one needs `customer:write`, or `user:write` on that account user.

```graphql
query TeamMembers {
  account_users {
    page(page_size: 25) {
      rows {
        record {
          uuid
          email
          scopes
          is_active
          last_login_at
        }
      }
    }
  }
}
```

```graphql
mutation AddTeamMember {
  add_account_user(email: "dev@example.com", scopes: "index:read:*") {
    uuid
    email
    scopes
  }
}
```

The new list of scopes replaces the old one:

```graphql
mutation ChangeScopes {
  update_account_user_scopes(
    account_user_uuid: "<account_user_uuid>"
    scopes: "index:read:* events:write:*"
  ) {
    uuid
    scopes
  }
}
```

```graphql
mutation DisableTeamMember {
  disable_account_user(account_user_uuid: "<account_user_uuid>") {
    uuid
    is_active
  }
}
```
