If you already have a refresh token (or credentials, if using IMAP) for your end 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, Custom auth allows you to simply provide the user refresh_token
to create a grant.
Use API request for Custom authentication
The following examples show a POST /v3/connect/custom
request and a sample response.
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": "1", "data": { "id": "<NYLAS_GRANT_ID>", "provider": "microsoft", "grant_status": "valid", "scope": ["Mail.Read", "User.Read", "offline_access"], "user_agent": "<USER_AGENT>", "ip": "<IP_ADDRESS>", "state": "<STATE>", "created_at": 1617817109, "updated_at": 1617817109 }}
Use Nylas SDKs for Custom authentication
You can use the v3 Nylas SDKs to set up Custom auth, as in the examples below.
import osimport sysfrom nylas import Clientfrom nylas.models.grants import CreateGrantRequestfrom 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 gemsrequire 'dotenv/load'require 'nylas'
# Initialize Nylas clientnylas = Nylas::Client.new( api_key: "<NYLAS_API_KEY>")
# Request bodyrequest_body = { provider: '<PROVIDER>', settings: {'username': '<USERNAME>', 'password': '<PASSWORD>'}, scope: 'email.read_only,calendar.read_only,contacts.read_only', state: '<STATE>'}
# Call Custom Authenticationauth = nylas.auth.custom_authentication(request_body)puts auth
package org.example;
// Import Nylas Packagesimport com.nylas.NylasClient;import com.nylas.models.*;// Import Packagesimport 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); }}
package org.example
// Import Nylas Packagesimport com.nylas.NylasClientimport 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)}
Creating a Custom auth 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 Custom 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.