ArchipadDevelopers

Authentication

Every request to the Archipad APIs, GraphQL and REST alike, carries an OAuth 2.0 bearer token (RFC 6750) issued by the Archipad identity provider, an OpenID Connect provider. The APIs check the token's signature against the provider's published keys, its issuer, its audience and its expiry. There are two ways to get one, depending on whether your integration acts on behalf of a person or on its own.

On behalf of a userAuthorization code flow with PKCE For an application a person uses: a web, mobile or desktop app, or a tool run under someone's own account. Server to serverClient credentials grant For an integration with no person present: a backend synchronising data, a scheduled job.

Before you start

You need an OAuth client registered with Archipad: a client ID, a client secret if your integration runs on a server, and the redirect URIs of your application if people sign in through it. Ask your Archipad contact for one. The provider's endpoints are published in its discovery document (OpenID Connect Discovery); the examples below name them as the document does.

Issuer
https://<identity-provider>
Discovery document
https://<identity-provider>/.well-known/openid-configuration
Audience
<audience>
GraphQL endpoint
https://<archipad-api>/graphql
This documentation is not configured with an identity provider: the values above are placeholders, your Archipad contact gives you the real ones.

On behalf of a user

For an application a person uses: a web, mobile or desktop app, or a tool run under someone's own account. The person signs in on the identity provider and your application receives a token that identifies them; the APIs then answer what that person is allowed to see. Use the authorization code flow with PKCE (RFC 6749, RFC 7636), which the OAuth 2.0 Security Best Current Practice recommends for every kind of client. A public client, such as a browser or mobile app, has no secret at all.

Generate a random code_verifier and derive its code_challenge with SHA-256, base64url-encoded.

Send the person to the authorization endpoint. The audience names the APIs the token is for; the state is a random value you check on the way back.

HTTP
GET <authorization_endpoint>
  ?response_type=code
  &client_id=<client-id>
  &redirect_uri=https://<your-app>/callback
  &scope=openid%20email
  &audience=%3Caudience%3E
  &state=<random-state>
  &code_challenge=<S256-challenge>
  &code_challenge_method=S256

Once signed in, the person is redirected to your redirect_uri with a code and the state. Refuse the response if the state is not the one you sent.

Exchange the code for a token at the token endpoint, proving the verifier. A confidential client also authenticates here, as in the server-to-server request below.

cURL
curl -X POST <token_endpoint> \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=authorization_code \
  -d client_id=<client-id> \
  -d redirect_uri=https://<your-app>/callback \
  -d code=<code> \
  -d code_verifier=<code-verifier>

The token endpoint answers the access token and its lifetime in seconds.

JSON · Response
{
  "access_token": "eyJhbGciOiJSUzI1NiIs…",
  "token_type": "Bearer",
  "expires_in": 3600
}

Server to server

For an integration with no person present: a backend synchronising data, a scheduled job. Your client authenticates with its own credentials and receives a token that represents it. Use the client credentials grant (RFC 6749), authenticating with HTTP Basic as the standard recommends.

Keep the secret on your servers
Never ship it in a browser or a mobile app.
cURL
curl -X POST <token_endpoint> \
  -u "<client-id>:<client-secret>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=client_credentials \
  -d scope=openid \
  -d audience=%3Caudience%3E

The answer has the same shape as above.

Calling the APIs

Send the token in the Authorization header of every request, to the GraphQL API as to the REST APIs. A GraphQL query, for instance:

cURL · GraphQL
curl -X POST https://<archipad-api>/graphql \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{ "query": "query { project(id: \"<project-id>\") { id name } }" }'
When a token is refused
The APIs reject a request whose token is missing, expired, or issued for another audience or by another provider; it also rejects a client that is not allowed to use them, even with a valid token. Ask your Archipad contact if a valid token is refused.

Token lifetime

A token is valid for expires_in seconds. Keep it and reuse it until shortly before it expires, then get a new one: do not request a token for every call. When a person's token expires, start the sign-in again, or use the refresh token if your client was granted one.

Try it

Get a token from the documentation

Sign in as an Archipad user, or enter your own client's credentials: the values above are filled in. GraphiQL, on the GraphQL API's overview and on each operation's page, then runs queries with it before you write any code.

Further reading