Authentication

The Duro GraphQL API uses Bearer token and API key (via x-api-key header) authentication. All API requests must include an authorization token in the header.

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 acting as your organization	An API key in the x-api-key header	This page
An application signing in as a human being — your own UI, a desktop tool, a CAD plugin	The account APIs: sign up, sign in, sessions, SSO	Account Management

Most integrations want an API key. If you need to authenticate individual people — including single sign-on, password reset, or managing sign-in methods — start with How Authentication Works.

Obtaining an API Authentication Token

To get started with the Duro API, you'll need to:

1. Create a Duro account at durohub.com

2. Navigate to your account settings

3. Generate an API token from the Developer section

4. Your URL to get an API key is: https://durohub.com/org/@<your org slug>/libs/<your library slug>/settings/api-keys

API Key Created Window

Using the Token

Include your API token in all requests using the x-api-key header:

x-api-key: YOUR_API_TOKEN

Token Security

• Never share your API tokens

• Rotate tokens regularly

• Use different tokens for development and production

• Store tokens securely in environment variables

Never commit API tokens to version control or expose them in client-side code.

Checking the Authenticated User

To confirm a token is valid and inspect the current identity, query me under the user namespace:

query {
  user {
    me {
      hasOrganizations
    }
  }
}

hasOrganizations is a non-null Boolean that returns true when the authenticated user belongs to at least one organization. It is useful in onboarding flows to decide whether to prompt the user to create or join an organization before making organization-scoped calls.

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 until the account is invited or approved — check it before issuing further requests.

See Current User for the full set of fields me returns.

Selecting an Organization

Most operations are scoped to a single organization, which you select with the x-organization header. It accepts either form:

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.

Never rely on a default. When a user belongs to several organizations, their membership list has no defined order, so omitting the header leaves the organization Duro picks for the request unpredictable. This is why document uploads now take their organization from this header instead of from the uploader's memberships.

Membership records returned with the authenticated user include organization.slug alongside the organization's id, so you can render a picker and build the header value without a second lookup — prefix the slug with @ to send the slug form:

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

Next Steps

Learn how to make your first API call in the Hello World guide.

To authenticate people rather than services — signup, sign-in, sessions, SSO, and password management — see Account Management.