Skip to content

auth

AccessType = Literal['online', 'offline'] module-attribute

Literal for the access type of the authentication URL.

Prompt = Literal['select_provider', 'detect', 'select_provider,detect', 'detect,select_provider'] module-attribute

Literal for the different supported OAuth prompts.

Provider = Literal['google', 'imap', 'microsoft', 'icloud', 'virtual-calendar'] module-attribute

Literal for the different authentication providers.

CodeExchangeRequest

Bases: TypedDict

Interface of a Nylas code exchange request

Attributes:

Name Type Description
redirect_uri str

Should match the same redirect URI that was used for getting the code during the initial authorization request.
code str

OAuth 2.0 code fetched from the previous step.
client_id str

Client ID of the application.
client_secret NotRequired[str]

Client secret of the application. If not provided, the API Key will be used instead.
code_verifier NotRequired[str]

The original plain text code verifier (code_challenge) used in the initial authorization request (PKCE).
Source code in nylas/models/auth.py 
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
class CodeExchangeRequest(TypedDict):
    """
    Interface of a Nylas code exchange request

    Attributes:
        redirect_uri: Should match the same redirect URI that was used for getting the code during the initial
            authorization request.
        code: OAuth 2.0 code fetched from the previous step.
        client_id: Client ID of the application.
        client_secret: Client secret of the application. If not provided, the API Key will be used instead.
        code_verifier: The original plain text code verifier (code_challenge) used in the initial
            authorization request (PKCE).
    """

    redirect_uri: str
    code: str
    client_id: str
    client_secret: NotRequired[str]
    code_verifier: NotRequired[str]

CodeExchangeResponse dataclass

Class representation of a Nylas code exchange response.

Attributes:

Name Type Description
access_token str

Supports exchanging the Nylas code for an access token, or refreshing an access token.
grant_id str

ID representing the new Grant.
scope Optional[str]

List of scopes associated with the token.
expires_in int

The remaining lifetime of the access token, in seconds.
email Optional[str]

Email address of the grant that is created.
refresh_token Optional[str]

Returned only if the code is requested using "access_type=offline".
id_token Optional[str]

A JWT that contains identity information about the user. Digitally signed by Nylas.
token_type Optional[str]

Always "Bearer".
provider Optional[Provider]

The provider that the code was exchanged with.
Source code in nylas/models/auth.py 
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
@dataclass_json
@dataclass
class CodeExchangeResponse:
    """
    Class representation of a Nylas code exchange response.

    Attributes:
        access_token: Supports exchanging the Nylas code for an access token, or refreshing an access token.
        grant_id: ID representing the new Grant.
        scope: List of scopes associated with the token.
        expires_in: The remaining lifetime of the access token, in seconds.
        email: Email address of the grant that is created.
        refresh_token: Returned only if the code is requested using "access_type=offline".
        id_token: A JWT that contains identity information about the user. Digitally signed by Nylas.
        token_type: Always "Bearer".
        provider: The provider that the code was exchanged with.
    """

    access_token: str
    grant_id: str
    expires_in: int
    email: Optional[str] = None
    refresh_token: Optional[str] = None
    scope: Optional[str] = None
    id_token: Optional[str] = None
    token_type: Optional[str] = None
    provider: Optional[Provider] = None

PkceAuthUrl dataclass

Class representing the object containing the OAuth 2.0 URL and the hashed secret.

Attributes:

Name Type Description
secret str

Server-side challenge used in the OAuth 2.0 flow.
secret_hash str

SHA-256 hash of the secret.
url str

The URL for hosted authentication.
Source code in nylas/models/auth.py 
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
@dataclass_json
@dataclass
class PkceAuthUrl:
    """
    Class representing the object containing the OAuth 2.0 URL and the hashed secret.

    Attributes:
        secret: Server-side challenge used in the OAuth 2.0 flow.
        secret_hash: SHA-256 hash of the secret.
        url: The URL for hosted authentication.
    """

    secret: str
    secret_hash: str
    url: str

ProviderDetectParams

Bases: TypedDict

Interface representing the object used to set parameters for detecting a provider.

Attributes:

Name Type Description
email str

Email address to detect the provider for.
all_provider_types NotRequired[bool]

Search by all providers regardless of created integrations. If unset, defaults to false.
Source code in nylas/models/auth.py 
171
172
173
174
175
176
177
178
179
180
181
class ProviderDetectParams(TypedDict):
    """
    Interface representing the object used to set parameters for detecting a provider.

    Attributes:
        email: Email address to detect the provider for.
        all_provider_types: Search by all providers regardless of created integrations. If unset, defaults to false.
    """

    email: str
    all_provider_types: NotRequired[bool]

ProviderDetectResponse dataclass

Interface representing the Nylas provider detect response.

Attributes:

Name Type Description
email_address str

Email provided for autodetection
detected bool

Whether the provider was detected
provider Optional[str]

Detected provider
type Optional[str]

Provider type (if IMAP provider detected displays the IMAP provider)
Source code in nylas/models/auth.py 
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
@dataclass_json
@dataclass
class ProviderDetectResponse:
    """
    Interface representing the Nylas provider detect response.

    Attributes:
        email_address: Email provided for autodetection
        detected: Whether the provider was detected
        provider: Detected provider
        type: Provider type (if IMAP provider detected displays the IMAP provider)
    """

    email_address: str
    detected: bool
    provider: Optional[str] = None
    type: Optional[str] = None

TokenExchangeRequest

Bases: TypedDict

Interface of a Nylas token exchange request

Attributes:

Name Type Description
redirect_uri str

Should match the same redirect URI that was used for getting the code during the initial authorization request.
refresh_token str

Token to refresh/request your short-lived access token
client_id str

Client ID of the application.
client_secret NotRequired[str]

Client secret of the application. If not provided, the API Key will be used instead.
Source code in nylas/models/auth.py 
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
class TokenExchangeRequest(TypedDict):
    """
    Interface of a Nylas token exchange request

    Attributes:
        redirect_uri: Should match the same redirect URI that was used for getting the code during the initial
            authorization request.
        refresh_token: Token to refresh/request your short-lived access token
        client_id: Client ID of the application.
        client_secret: Client secret of the application. If not provided, the API Key will be used instead.
    """

    redirect_uri: str
    refresh_token: str
    client_id: str
    client_secret: NotRequired[str]

TokenInfoResponse dataclass

Class representation of a Nylas token information response.

Attributes:

Name Type Description
iss str

The issuer of the token.
aud str

The token's audience.
iat int

The time that the token was issued.
exp int

The time that the token expires.
sub Optional[str]

The token's subject.
email Optional[str]

The email address of the Grant belonging to the user's token.
Source code in nylas/models/auth.py 
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
@dataclass_json
@dataclass
class TokenInfoResponse:
    """
    Class representation of a Nylas token information response.

    Attributes:
        iss: The issuer of the token.
        aud: The token's audience.
        iat: The time that the token was issued.
        exp: The time that the token expires.
        sub: The token's subject.
        email: The email address of the Grant belonging to the user's token.
    """

    iss: str
    aud: str
    iat: int
    exp: int
    sub: Optional[str] = None
    email: Optional[str] = None

URLForAdminConsentConfig

Bases: URLForAuthenticationConfig

Configuration for generating a URL for admin consent authentication for Microsoft.

Attributes:

Name Type Description
credential_id str

The credential ID for the Microsoft account
Source code in nylas/models/auth.py 
52
53
54
55
56
57
58
59
60
class URLForAdminConsentConfig(URLForAuthenticationConfig):
    """
    Configuration for generating a URL for admin consent authentication for Microsoft.

    Attributes:
        credential_id: The credential ID for the Microsoft account
    """

    credential_id: str

URLForAuthenticationConfig

Bases: TypedDict

Configuration for generating a URL for OAuth 2.0 authentication.

Attributes:

Name Type Description
client_id str

The client ID of your application.
redirect_uri str

Redirect URI of the integration.
provider NotRequired[Provider]

The integration provider type that you already had set up with Nylas for this application. If not set, the user is directed to the Hosted Login screen and prompted to select a provider.
access_type NotRequired[AccessType]

If the exchange token should return a refresh token too. Not suitable for client side or JavaScript apps.
prompt NotRequired[Prompt]

The prompt parameter is used to force the consent screen to be displayed even if the user has already given consent to your application.
scope NotRequired[List[str]]

A space-delimited list of scopes that identify the resources that your application could access on the user's behalf. If no scope is given, all of the default integration's scopes are used.
include_grant_scopes NotRequired[bool]

If set to true, the scopes granted to the application will be included in the response.
state NotRequired[str]

Optional state to be returned after authentication
login_hint NotRequired[str]

Prefill the login name (usually email) during authorization flow. If a Grant for the provided email already exists, a Grant's re-auth will automatically be initiated.
Source code in nylas/models/auth.py 
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
class URLForAuthenticationConfig(TypedDict):
    """
    Configuration for generating a URL for OAuth 2.0 authentication.

    Attributes:
        client_id: The client ID of your application.
        redirect_uri: Redirect URI of the integration.
        provider: The integration provider type that you already had set up with Nylas for this application.
            If not set, the user is directed to the Hosted Login screen and prompted to select a provider.
        access_type: If the exchange token should return a refresh token too.
            Not suitable for client side or JavaScript apps.
        prompt: The prompt parameter is used to force the consent screen to be displayed even if the user
            has already given consent to your application.
        scope: A space-delimited list of scopes that identify the resources that your application
            could access on the user's behalf.
            If no scope is given, all of the default integration's scopes are used.
        include_grant_scopes: If set to true, the scopes granted to the application will be included in the response.
        state: Optional state to be returned after authentication
        login_hint: Prefill the login name (usually email) during authorization flow.
            If a Grant for the provided email already exists, a Grant's re-auth will automatically be initiated.
    """

    client_id: str
    redirect_uri: str
    provider: NotRequired[Provider]
    access_type: NotRequired[AccessType]
    prompt: NotRequired[Prompt]
    scope: NotRequired[List[str]]
    include_grant_scopes: NotRequired[bool]
    state: NotRequired[str]
    login_hint: NotRequired[str]