Only show these results:

Authorize API requests

In this step, you'll learn how to authorize requests to the Nylas v3 APIs.

What is authorization?

When an end user authenticates their account with Nylas, they're telling their email provider that they are a legitimate owner of the account, and yes, they're giving Nylas access to it. The provider then gives Nylas an access token for the account, which it saves in a grant record. As a developer, you can use the grant ID (with some other information, like the Nylas application's client ID and API token) to make API requests for the user's data.

🔍 Confusing language alert: "Authentication" is the process of proving who you are, and that you have the right to make decisions about an account and its data. However, when you make API requests you use an authorization header to pass a token or other credential. The token is like a backstage pass: it authorizes you to make requests. But then the different types of API authorization headers are known as "authentication" types. Even worse, both of these are sometimes shortened as "auth". We try to be as clear as possible in the Nylas docs about which one we mean.

Authorizing API requests

Nylas v3 has two ways to authorize API requests: you can use the application's API key, or an access token for a specific grant. Both of these methods use HTTP Bearer authentication - this means that the token is a meaningless string, not a password, and that you send it in the Authorization header of your request instead of in the request body.

If you plan to access user data, such as email messages or calendars, you can use either an API key or an access token to authorize requests. However, if you make API requests that read or modify data about the Nylas application (for example subscribing to webhooks, or changing auth information) you can only authorize them with an API key.

For this demo, we'll use an API key!

Generate an API key

This tutorial uses API key authorization. Follow these steps to generate an API key:

  1. From the Sandbox application, click API keys in the left navigation menu.
  2. Click Generate new key.
  3. Give the key a name and set its expiration date, then click Generate key.

    ⚠ī¸ Nylas shows the API key secret on the next screen, and never shows it again. Copy it and keep it somewhere safe, like a secrets manager. If you lose the secret, you'll have to generate a new API key.

You can have multiple API keys for the same application.

(Optional) Developer tools for authorizing requests

Copy-pasting API keys and grant IDs into code snippets can be tedious, so we've got some shortcuts. This section lists some tools you can use to save time applying your keys if you plan to try a lot of APIs.

Create an .env file

An .env file is a text file that contains environment variables. You can use an .env file to save your API key and grant IDs as variables, then reference them in your API requests from the command line.

  1. Copy and paste the text below into an .env file in your development directory.
  2. Add the Sandbox client ID, API key, and grant ID from this tutorial, and save the file.
  3. Use the source <path to .env file> command in your terminal to apply the variables.

ℹī¸ Depending on the terminal or shell program that you're using, the exact command to apply an ENV file might be different. Check your program's documentation for the exact command.

NYLAS_CLIENT_ID=(paste here)
NYLAS_API_KEY=(paste here)
NYLAS_GRANT_ID=(paste here)

Use the Nylas SDKs

If you're developing in Node.js, Ruby, Python, or Kotlin/Java, Nylas maintains SDKs so you can integrate easily with projects in these languages. All of these SDKs allow you to save and reference an API key as part of their initialization step. See the SDK documentation for more information.

Use Postman

Postman is a tool that allows developers to make API requests and save them for later. You can use Postman to save your API key, and then use it in your API requests from the Postman interface.

Try out the Nylas Postman collection. For more information, read Nylas' Postman collection documentation.

Ready to make some API calls? Let's go!