Authentication

Authenticating Calls

To authenticate API calls, the client must add the following header:

Authorization: Bearer TOKEN

where TOKEN is obtained by one of the methods below.

Token Types

There are three types of tokens which can have one of two access scopes.

Type	Scope
Personal Access Token (`PAT`)	`personal`	Generated manually from the integrations page. Doesn't expire, and can be revoked at any time.
Workspace Access Token (`WAT`)	`workspace`	Generated manually from the integrations page. Doesn't expire, and can be revoked at any time.
OAuth Token	`personal`, `workspace`	Issued through the OAuth2 Flow. Expires, must be refreshed.

Scope
`personal`	Provides the same access level as the user who authorized the token.
`workspace`	Provides FULL DATA ACCESS of the workspace. Can be generated by workspace admins only.

NOTE: The workspace scope is not available on all plans.
Check https://grain.com/pricing to see if your plan includes Workspace API.

OAuth2 Flow

This authentication method is for developers building integrations with Grain to be used by any Grain users.

The API supports a standard OAuth2 Authorization Code flow, including the PKCE extension for client-side only authentication. A redirect URI prefix is required to register a new client. For browser-based client applications, a list of CORS origins can also be added.

Authorization Code

Step 1

Obtain the client_id and client_secret (only for server-side applications) credentials.

Step 2

Open the url https://grain.com/_/public-api/oauth2/authorize with the following query params.

Param
client_id	Obtained separately in Step 1
redirect_uri	Must be prefixed by the registered URI prefix
response_type	Must be `code`
code_challenge	A random string, hashed with `SHA256` and `base64` URL encoded
code_challenge_method	Must be `S256`
scopes	`personal` or `workspace`. Defaults to `personal`

Step 3

If the user is not already signed in to Grain, they will be prompted to sign in. After being authenticated, the user will be prompted to confirm the OAuth2 connection.

Step 4

The user will be redirected to redirect_uri from Step 2 with the code query param.

Step 5

Make a POST request to generate the token. See OAuth2 Generate Token

Diagram

sequenceDiagram
  participant you as You
  actor user as User
  participant grain as Grain
  
  Note right of you: Step 1
  you-->>grain: Request Client ID & Secret (manually)
  grain-->>you: Client ID & Secret

  Note right of you: Step 2
  user->>you: Requests OAuth
  you->>user: Open or Redirects to oauth2/authorize
  user->>grain: oauth2/authorize
  
  Note left of grain: Step 3
  grain->>user: Requests login
  user->>grain: Login
  
  grain->>user: Requests Confirm OAuth
  user->>grain: Confirms

	Note left of grain: Step 4  
  grain->>user: Redirects to redirect_uri w/code
  user->>you: redirect_uri w/code
  
  Note right of you: Step 5
  you->>grain: POST oauth2/token w/code
  grain->>you: access_token & refresh_token
  
  Note right of you: Refresh
  you->>grain: POST oauth2/token w/refresh_token
  grain->>you: access_token & refresh_token

Refresh Token

After the access_token has expired, you may generate a new one.

See OAuth2 Refresh Token