Create grants with Custom authentication
Nylas v3 preserves Native authentication ("Bring your own token") almost unchanged, but renames it "Custom authentication". 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 used Native auth in Nylas v2.x, the only changes are to the Nylas API URLs, the requirement that you create a connector (previously called an "integration") for your application, and the change from token authentication to bearer-token authentication.
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' \
--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",
"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
}
}
Use Nylas SDKs for Custom authentication
You can use the v3 Nylas SDKs to set up Custom auth, as in the examples below.
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.*;
// 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);
}
}
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)
}
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.
⚠️ Avoid storing user credentials by making a Custom 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.
What's next?
Now that you have created a connector and received a grant, you can do the following tasks: