Creating grants with Bring Your Own Authentication

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.

If you’re using multiple provider applications with a single connector, you can include the credential_id in the settings object when making a Bring Your Own Authentication request to specify which provider application should be used.

Create grant with Bring Your Own Authentication

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": "leyah@hotmail.com",
    "scope": ["Mail.Read", "User.Read", "offline_access"],
    "user_agent": "<USER_AGENT>",
    "ip": "<IP_ADDRESS>",
    "state": "<STATE>",
    "created_at": 1617817109,
    "updated_at": 1617817109
  }
}

from nylas import Client

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

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

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

require 'nylas'

nylas = Nylas::Client.new(
  api_key: "<NYLAS_API_KEY>",
)

request_body = {
  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)
puts auth

import com.nylas.NylasClient
import com.nylas.models.*

fun main() {
    val nylas: NylasClient = NylasClient(
        apiKey = "<NYLAS_API_KEY>"
    )

    val provider = AuthProvider.ICLOUD
    val settings = mapOf("username" to "<USERNAME>", "password" to "<PASSWORD>")
    val scopes = listOf("email.read_only", "calendar.read_only", "contacts.read_only")

    val requestBody = CreateGrantRequest(provider, settings, "<STATE>", scopes)
    val grant = nylas.auth().customAuthentication(requestBody)

    println(grant)
}

import com.nylas.NylasClient;
import com.nylas.models.*;

import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class Main {
    public static void main(String[] args) throws
            NylasSdkTimeoutError, NylasApiError {
        NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();

        AuthProvider provider = AuthProvider.ICLOUD;

        Map<String, Object> settings = new HashMap<>();
        settings.put("username", "<USERNAME>");
        settings.put("password", "<PASSWORD>");

        List<String> scopes = List.of(
            "email.read_only", "calendar.read_only", "contacts.read_only");

        CreateGrantRequest requestBody =
            new CreateGrantRequest(provider, settings, "<STATE>", scopes);

        Response<Grant> grant = nylas.auth().customAuthentication(requestBody);
        System.out.println(grant);
    }
}

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.

Creating grants with Bring Your Own Authentication

Create grant with Bring Your Own Authentication

Create Bring Your Own Authentication login page