Manually creates a grant using the Bring Your Own (BYO) Authentication flow. If you're handling the OAuth flow in your own project or you want to migrate existing users, BYO Auth lets you provide the user's refresh_token to create a grant.

If a user previously authenticated with your Nylas application using the same email address, Nylas detects this and re-authenticates their existing grant instead of creating a new one. The API response contains the user's existing grant_id.

Supported providers

Pick the request body variant that matches your provider:

• Refresh token — OAuth providers (google, microsoft, yahoo, zoom) using a standard refresh token.
• Credential override — OAuth providers, but using a stored credential record to swap in different client credentials.
• Microsoft bulk auth — Microsoft App Permissions. Requires a connector credential and the admin consent flow.
• Google bulk auth — Google Service Accounts. Requires a connector credential and the Service Account flow.
• IMAP — direct IMAP/SMTP credentials for any IMAP provider.
• iCloud — an iCloud email address plus an Apple app password.
• EWS — on-premises Microsoft Exchange; hosted Exchange should use Microsoft Graph instead.
• Zoom Meetings — Zoom OAuth. Your OAuth app must include the granular scopes meeting:write:meeting, meeting:update:meeting, and meeting:delete:meeting.
• Nylas (Agent Account) — a fully Nylas-hosted Agent Account email and calendar mailbox on a domain you've registered with Nylas.

{
  "settings": {
    "refresh_token": "1//09XpDHQ6hq6PrCgYIARAAGAkSNwF..."
  }
}

{
  "request_id": "5967ca40-a2d8-4ee0-a0e0-6f18ace39a90",
  "data": {
    "account_id": "df0yq6c9okc6t9j4ejd5nyrt7",
    "created_at": 1617817109,
    "email": "nyla@example.com",
    "grant_status": "valid",
    "id": "e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47",
    "ip": "1.1.1.1",
    "name": "Nyla",
    "provider": "microsoft",
    "provider_user_id": "b16f171c-6640-4edd-a598-e507b546d841",
    "scope": [
      "Mail.Read",
      "User.Read",
      "offline_access"
    ],
    "email_aliases": [
      "email_alias1@example.com",
      "email_alias2@example.com"
    ],
    "state": "my-state",
    "updated_at": 1617817109,
    "workspace_id": "abf6ff99-05ad-4c0a-aaf8-400aacf2470a",
    "credential_id": "c123f8e1a-eb1c-41c0-b6a6-d2e59daf7f47"
  }
}