Legacy Docs

If you were part of the API Beta you can find the legacy docs here:

• (V1) Personal API Docs
• (V1) Workspace API Docs

Please be aware that v1 will be sunset and some features won’t be translated to v2. As such, we don’t recommend usage of v1 anymore.

Authentication

Personal Access Token

These tokens can be generated to grant access to the API in a per-user basis. Requests authenticated with these tokens are considered as “Personal API” and will have the same level of access as the user that generated the token has.

PATs can be generated here: https://grain.com/app/settings/integrations?tab=api

Workspace Access Token

These tokens can be generated to grant access to the API for a general workspace use case.

Requests authenticated with these tokens are considered as “Workspace API” and will have access to ALL DATA from your workspace.

WAT’s can be generated here, by users with access: https://grain.com/app/settings/integrations?tab=api

OAuth2 Flow

This authentication method is for developers building integrations with Grain to be used by any Grain users. Requests authenticated with these tokens are considered as “Personal API” and will have the same level of access as the authenticated user has.

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.

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