Creating grants with Bring Your Own Authentication

Bring Your Own (BYO) Authentication is available for Contract plans only.

If you already have a refresh token (or credentials, if using IMAP) for your users from your own authentication implementation, you can use it with the Nylas APIs to create a grant and get the grant_id, which you then use in requests to the provider. If you are handling the OAuth flow in your own application or want to migrate existing users, Bring Your Own Authentication allows you to simply provide the user refresh_token to create a grant.

Create grant with Bring Your Own Authentication

RequestResponse (JSON)PythonRubyKotlinJava

curl --request POST \
  --url "https://api.us.nylas.com/v3/connect/custom" \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>'\
  --header 'Content-Type: application/json' \
  --data '{
    "provider": "microsoft",
    "settings": {
      "refresh_token":"<REFRESH_TOKEN>"
    },
    "state": "<STATE>"
  }'

{
  "request_id": "5fa64c92-e840-4357-86b9-2aa364d35b88",
  "data": {
    "id": "<NYLAS_GRANT_ID>",
    "provider": "microsoft",
    "grant_status": "valid",
    "email": "[email protected]",
    "scope": ["Mail.Read", "User.Read", "offline_access"],
    "user_agent": "<USER_AGENT>",
    "ip": "<IP_ADDRESS>",
    "state": "<STATE>",
    "created_at": 1617817109,
    "updated_at": 1617817109
  }
}

import os
import sys
from nylas import Client
from nylas.models.grants import CreateGrantRequest
from nylas.models.auth import Provider

nylas = Client(
  <'NYLAS_API_KEY'>,
  <'NYLAS_API_URI'>
)

request_body = CreateGrantRequest(
{
  "provider": "<PROVIDER>",
  "settings": {"username": "<USERNAME>", "password" : "<PASSWORD>"},
  "scope": ["email.read_only", "calendar.read_only", "contacts.read_only"],
  "state": "<STATE>"
}
)

auth = nylas.auth.custom_authentication(request_body)
print(auth)

# Load gems
require 'dotenv/load'
require 'nylas'

# Initialize Nylas client
nylas = Nylas::Client.new(
  api_key: "<NYLAS_API_KEY>"
)

# Request body
request_body = {
  provider: '<PROVIDER>',
  settings: {'username': '<USERNAME>', 'password': '<PASSWORD>'},
  scope: 'email.read_only,calendar.read_only,contacts.read_only',
  state: '<STATE>'
}

# Call Custom Authentication
auth = nylas.auth.custom_authentication(request_body)
puts auth

package org.example

// Import Nylas Packages
import com.nylas.NylasClient
import com.nylas.models.*

fun main() {

    // Initialize Nylas client
    val nylas: NylasClient = NylasClient(
        apiKey = <"V3_TOKEN_API">
    )
    // Select the provider
    val provider = AuthProvider.ICLOUD
    // Build out the settings
    val settings = mapOf<String, String>("username" to <"USERNAME">,
        "password" to <"PASSWORD">)
    // Build our the scope
    val scopes = listOf("email.read_only", "calendar.read_only", "contacts.read_only")
    // Create the request body
    val requestBody = CreateGrantRequest(provider, settings, "<STATE>", scopes)
    val auth = nylas.auth().customAuthentication(requestBody)
    // Generate the grant
    println(auth)
}

package org.example;

// Import Nylas Packages
import com.nylas.NylasClient;
import com.nylas.models.*;
// Import Packages
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class Main {
    public static void main(String[] args) throws
            NylasSdkTimeoutError, NylasApiError {
        // Initialize the Nylas client
        NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
        // Select the provider
        AuthProvider provider = AuthProvider.ICLOUD;
        // Build out the settings
        Map<String, String> settings = new HashMap<String, String>();
        settings.put("username","<USERNAME>");
        settings.put("password","<PASSWORD>");
        // Build our the scopes
        List<String> scope = new ArrayList<String>();
        scope.add("email.read_only");
        scope.add("calendar.read_only");
        scope.add("contacts.read_only");
        // Create the request body
        CreateGrantRequest request_body = new CreateGrantRequest(provider,settings, "<SCOPE>", scope);
        // Generate the grant
        Response<Grant> auth = nylas.auth().customAuthentication(request_body);
        System.out.println(auth);
    }
}

Create Bring Your Own Authentication login page

Nylas provides a login page for Hosted authentication that uses the detect provider API to route user logins to the correct provider.

If you’re using Bring Your Own (BYO) authentication instead, you must create a login page for your app where your users enter their login credentials. This should be branded, and can use the Detect Provider endpoint to help route user logins to use the correct connector.

Avoid storing user credentials by making a BYO Authentication request directly from your login page with the user-provided credentials. If you must store the credentials, make sure you do so securely. For more information, see Security best practices.