Creating grants with Bring Your Own Authentication

Copy as MarkdownCurl Markdown

Open in

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.

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

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
  }
}

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);
    }
}

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.