Getting Started

info

This page walks you through the essential steps to start using our API — from authenticating securely to running your first GraphQL query. Whether you're building an integration, testing a feature, or just exploring, this guide will help you hit the ground running.

Get Setup

To get started and use the API you first need to:

• Create an Ansarada account
• Request access to the API

We’ll send your credentials:

• client_id
• client_secret

Authentication

Get authorised

Redirect your user to the following URL to begin the OAuth 2.0 flow:

GET https://auth.au.ansarada.com/authorize?
  audience=https://api.ansarada.com/graphql&
  response_type=code&
  client_id={client_id}&
  redirect_uri={redirect_uri}

Parameter	Description
audience	Must be https://api.ansarada.com/graphql. This defines the intended recipient of the token.
response_type	Denotes the kind of credential that will be returned. For this flow, the value must be code.
client_id	Your application's Client ID.
redirect_uri	The URL to which the browser will be redirected to after authorisation has been granted by the user. The Authorisation Code will be available in the code URL parameter.
state (optional)	An opaque value the application adds to the initial request that will be included when redirecting back to the application. This value could be used by the application to prevent CSRF attacks.
scope (optional)	The list of access scopes that defines specific actions your application can be allowed to do on a user's behalf. These must be separated by a space. You can request any of the standard OpenID Connect (OIDC) scopes.

The purpose of this call is to obtain consent from the user to invoke the API on their behalf. This process will authenticate the user and obtain consent, unless consent has been previously given.

Once the user successfully authenticates and grants consent, they will be redirected back to your specified redirect_uri. This redirect URL will contain an authorisation code as a query parameter. For example:

https://www.awesome.company/?code=aBcdAbCd_Yxyxoxa

Exchange Authorisation Code for Tokens

Use the code from the previous step to request access & refresh tokens:

POST https://auth.au.ansarada.com/oauth/token
Request body:
{
  "grant_type": "authorization_code",
  "client_id": "{client_id}",
  "client_secret": "{client_secret}",
  "code": "{code}",
  "redirect_uri": "{redirect_uri}"
}

Parameter	Description
grant_type	This must be authorization_code
client_id	Your application's Client ID
client_secret	Your application's Client Secret
code	The Authorisation Code received from the initial authorise call
redirect_uri	The URL must match exactly the redirect_uri passed to /authorize

Example response

{
  "access_token": "eyJz93a...k4laUWw",
  "expires_in": 86400,
  "token_type": "Bearer"
}

DataRoom-scoped Token

Some GraphQL queries and mutations require a DataRoom-scoped access token, which includes additional Data Room context.

To obtain one, include dataroom_node_id and dataroom_user_node_id to the initial authorise call:

GET https://auth.au.ansarada.com/authorize?
  audience=https://api.ansarada.com/graphql&
  response_type=code&
  client_id={client_id}&
  redirect_uri={redirect_uri}&
  dataroom_node_id={dataroom_id}&
  dataroom_user_node_id={dataroom_user_id}

These tokens are scoped to a specific Data Room and user. Make sure both IDs are valid. Learn how to obtain them here.

Use Refresh Token

By default, access tokens expire one day after being issued. To maintain the session without requiring the user to log in again, you can use the refresh token to obtain a new access token.

To receive a refresh token, you must add extra parameters when getting authorized. Include offline_access in the scope parameter of the initial authorise call:

GET https://auth.au.ansarada.com/authorize?
  audience=https://api.ansarada.com/graphql&
  response_type=code&
  client_id={client_id}&
  redirect_uri={redirect_uri}&
  scope=offline_access

When you successfully exchange the code for an access token, the response will include:

{
  "access_token": "eyJz93a...k4laUWw",
  "refresh_token": "dEf89...",
  "token_type": "Bearer"
}

If the access token expires, you can use the refresh token obtained from the previous response to get a new access token:

POST https://auth.au.ansarada.com/oauth/token
Request body
{
  "grant_type": "refresh_token",
  "client_id": "{client_id}",
  "client_secret": "{client_secret}",
  "refresh_token": "{refresh_token}"
}

To refresh a DataRoom-scoped token, please include dataroom_node_id and dataroom_user_node_id in the above request.

The response will include a new access token, its type, its lifetime (in seconds), and the granted scopes. If the scope of the initial token included openid, then a new ID token will be in the response as well.

{
  "access_token": "eyJ...MoQ",
  "expires_in": 86400,
  "scope": "offline_access",
  "token_type": "Bearer"
}

tip

Refresh tokens are long-lived, but they do not last forever.

• Idle lifetime: 14 days.
• After 30 days, the refresh token will expire and cannot be used to obtain new access tokens.
• When a refresh token expires, the user must re-authenticate through the full authorization flow.
• Refresh tokens will automatically be invalidated after use and exchanged for new tokens to prevent replay attacks.

Make GraphQL Requests

Once you have a valid access token, send POST requests to:

https://api.ansarada.com/v1/graphql

Include the token in your headers:

Authorization: Bearer {access_token}
Content-Type: application/json

Example body:

{
  "query": "query { me { email firstName lastName } }"
}