> For the complete documentation index, see [llms.txt](https://docs.durohub.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.durohub.com/getting-started/authentication.md).

# Authentication

Integrations authenticate to the Duro GraphQL API with an **API key**, sent in the `x-api-key` header on every request.

### Which one do you need?

Duro has two authentication mechanisms, and they serve different callers:

| You are…                                                      | Use                                                                                                                     | Read                                                                                          |
| ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| A script, integration, or backend service                     | An **API key** in the `x-api-key` header. The key acts as the user who created it, in the one library it was created in | This page                                                                                     |
| Your organization's identity provider, signing your people in | **SAML SSO** and **SCIM**                                                                                               | [Account Management](https://docs.durohub.com/account-management/how-authentication-works.md) |

{% hint style="info" %}
Most integrations want an API key. People sign in through Duro's own apps; the account endpoints behind them accept requests only from Duro's own web origin, so a third-party app cannot call them. To connect your identity provider instead, start with [How Authentication Works](https://docs.durohub.com/account-management/how-authentication-works.md).
{% endhint %}

### Obtaining an API Authentication Token

API keys are created per library:

1. Create a Duro account at [durohub.com](https://durohub.com)
2. Open the library the integration works in, then go to **Settings → API Keys**
3. Click **Create** and copy the key

The API Keys page for a library is at `https://durohub.com/org/@<your org slug>/libs/<your library slug>/settings/api-keys`. In the EU or GovCloud region, use your region's Duro web address instead of `durohub.com`. Creating keys requires the `organization.api_keys.manage` permission.

An API key acts as the user who created it, with that user's role, in the key's library. It is pinned to the one library it was created in: every request made with it works in that library.

![API Key Created Window](https://1319565474-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOJejmhbdeb0yjsYB69x4%2Fuploads%2Fgit-blob-ab407478cd18c16a5b67a164d3d2e817fe58322e%2Fapi-key-created-window.png?alt=media)

### Using the Token

Send the key in the `x-api-key` header on every request, together with the organization and library it belongs to:

```http
x-api-key: YOUR_API_TOKEN
x-organization: @your-org
x-library: @your-org/your-library
```

| Header           | Required                  | Value                                                               |
| ---------------- | ------------------------- | ------------------------------------------------------------------- |
| `x-api-key`      | Always                    | The key itself. Send it as-is — do **not** prefix it with `Bearer`. |
| `x-organization` | Always                    | The organization of the key's library, by UUID or `@slug`.          |
| `x-library`      | Library-scoped operations | The library the key was created in.                                 |

`x-library` must name the key's library, and `x-organization` must be that library's organization.

Requests go to `https://api.durohub.com/graphql`. Using the EU or GovCloud region? Use your region's host — see [Endpoints](https://docs.durohub.com/readme.md#endpoints).

### Managing API Keys

Managing keys needs the `organization.api_keys.manage` permission, and you manage only keys you created. List them to get each key's `id`:

```graphql
query ListMyApiKeys {
  apiKeys(filter: { isArchived: false }) {
    success
    result {
      id
      name
      libraryId
      expirationDate
    }
  }
}
```

`update`, `rotateApiKey` and `deactivate` each select the key by **exactly one** of `id` or `apiKey` (the raw key). Supplying both, or neither, returns `success: false` with "Provide exactly one of id or apiKey". Prefer `id`: it is stable for the life of the key, and no secret has to leave your system.

```graphql
mutation RotateApiKey {
  apiKey {
    rotateApiKey(input: { id: "api-key-uuid" }) {
      success
      errors
      result {
        id
        rawKey
        expirationDate
      }
    }
  }
}
```

Rotating issues a new key and stops the old one. The new raw key is in `result.rawKey` and is shown only once, so store it before you discard the response. `update` changes `name`, `description` or `isArchived` through `requestedChanges`; `deactivate` revokes the key immediately.

Only the raw key authenticates. Duro never returns a key's stored hash, and a hash sent as `x-api-key` is rejected with `UNAUTHENTICATED`.

### Token Security

* Never share your API tokens
* Rotate keys regularly — see [Managing API Keys](#managing-api-keys)
* Use different tokens for development and production
* Store tokens securely in environment variables

{% hint style="warning" %}
Never commit API tokens to version control or expose them in client-side code.
{% endhint %}

### Checking the Authenticated User

To confirm a key is valid and see who it acts as, query `me` under the `user` namespace:

```graphql
query {
  user {
    me {
      permitted
      hasOrganizations
      user {
        id
        name
        primaryEmail
      }
    }
  }
}
```

`me.user` is the user who created the key. `hasOrganizations` is a non-null `Boolean` that returns `true` when that user belongs to at least one organization.

A valid token is necessary but not sufficient: `me.permitted` reports whether the identity is allowed to use Duro at all. When it is `false`, every data operation is refused with [`ACCESS_NOT_PERMITTED`](https://docs.durohub.com/advanced-topics/error-handling.md#access-errors) until the account is invited or approved — check it before issuing further requests.

See [Current User](https://docs.durohub.com/getting-started/current-user.md) for the full set of fields `me` returns.

To discover which library a key belongs to, query `library.current`:

```graphql
query {
  library {
    current {
      id
      name
      slug
      organization {
        id
        slug
      }
    }
  }
}
```

### Selecting an Organization

Every request names its organization in the `x-organization` header. It accepts either form:

```http
x-organization: 550e8400-e29b-41d4-a716-446655440000
x-organization: @acme-corp
```

Duro validates the value against the authenticated caller's organization memberships on every request. A UUID or slug you are not a member of is rejected rather than silently falling back to another organization, so the header is safe to drive directly from user input such as an organization picker.

The header is required on every request. With an API key, it must be the organization of the key's library. [Document uploads](https://docs.durohub.com/core-concepts/documents.md#organization-context-for-uploads) also take their organization from this header.

The authenticated user's memberships include `organization.slug` alongside the organization's `id`, so you can build the header value without a second lookup — prefix the slug with `@` to send the slug form:

```graphql
query {
  user {
    me {
      user {
        organizationMemberships {
          organization {
            id
            slug
          }
        }
      }
    }
  }
}
```

```json
{
  "organization": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "slug": "acme-corp"
  }
}
```

### Next Steps

Learn how to make your first API call in the [Hello World](https://docs.durohub.com/getting-started/hello-world.md) guide.

To sign your people in through your identity provider with SSO, or to provision them with SCIM, see [Account Management](https://docs.durohub.com/account-management/how-authentication-works.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.durohub.com/getting-started/authentication.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
