Authenticate with the API
GraphQL supports two authentication modes:
| Mode | Coverage | Header | Best for |
|---|---|---|---|
| OAuth 2.0 | Supported subset only (the API-key operations, except generateComponentToken) | Authorization: Bearer <access-token> | Integrations acting on behalf of a Legalesign user, who logs in and consents |
| API Key | Supported subset only | Authorization: Bearer <api-key> | Server-side automation and common send/read flows |
Both modes support the same set of operations. An OAuth token acts as the user who authorised it, with that user's permissions.
API Key Authentication
Create a GraphQL-enabled API key in the Developer Portal, then send it as a bearer token:
POST /graphql HTTP/1.1
Host: graphql.uk.legalesign.com
Content-Type: application/json
Authorization: Bearer ak_<environment>_<key-id>.<secret>
{"query": "{ user { id email } }"}
GraphQL only needs
Authorization: Bearer. Nox-organisationor other custom headers are required.
Check the supported GraphQL operations and the auth badges on query and mutation reference pages before using an operation with an API key.
OAuth 2.0 Authentication
OAuth 2.0 lets your application act on behalf of a specific Legalesign user, for the operations that API keys support, except generateComponentToken (see the supported GraphQL operations). The user logs in and explicitly consents. Your application never handles their password.
Register an OAuth client in the Developer Portal, then follow the OAuth client guide for the complete integration steps. Your server authenticates to the token endpoint with the client secret, as well as PKCE.
Once you have an access token, use it identically to an API key:
POST /graphql HTTP/1.1
Host: graphql.uk.legalesign.com
Content-Type: application/json
Authorization: Bearer eyJ...
{"query": "{ user { id email } }"}
Access tokens expire after one hour. Use the refresh token to obtain a new one without the user re-authenticating. A refresh token expires if it is not used for 30 days, and the user's authorisation as a whole lasts 12 months from when they last approved your application, after which the user authorises again. Refresh tokens rotate on every use, so refresh from one place at a time and save the new token each time.
OAuth tokens are accepted by the GraphQL API only, not the REST API. A token acts with the authorised user's own permissions, and is not currently limited to your organisation's data. See the OAuth client guide for what that means before you register a client.
Widget and Component Authorization
Authenticated widgets such as the Document Viewer and Signer need a short-lived token passed to their token attribute. Use an API key to call generateComponentToken server-side and pass the returned token to the widget.
See Widget Authorization for the complete flow and browser security guidance.