Authentication overview

Neon uses 3 basic forms of authentication, depending on the use case:

  • JWT token via Username/Password: You generate these by using the POST /access-tokens endpoint of the API. You will be given back a long string that is a JWT token, and will be placed into all authenticated requests to the Neon API. Note that all JWT tokens have a maximum time to live of 1 hour, but can be renewed indefinitely by using the /access-tokens/refresh endpoint.
  • JWT token via API Keys : You can generate API keys for your own account. These keys are primarily used when you are writing an integration that runs in an automated fashion and therefor the user cannot perform a login. Realize that generating an API key puts far more security responsibility upon you, so if possible prefer the use of username/password. API Keys are created/viewed using the /api-keys endpoint (POST and GET, respectively). You convert an API key to a JWT token using the POST /api-keys/access-token endpoint. The API key runs with the privileges of the user that created it. Once you have its JWT token, it is used the same as one created via username/password. Be aware that while an API key can live for up to 1 year, the tokens generated by it only last for up to an hour, same as the ones generated by username/password. Use the /access-tokens/refresh endpoint to keep them alive.
  • Device keys : Some API methods are related to a specific device (such as the VAST integrations.) Such endpoints rely on the device key and are not authenticated via token.
First authentication using your username and password

For your first use of the API, we want to authenticate with your username and password from the website. Go to the API Browser, and expand the POST /access-tokens endpoint, and hit the "Try It Out" button. That will make the request editable. Now make these changes:

  1. Replace "user@example.com" with your email address
  2. Replace "string" with your password
  3. If you created an advertising account, change "OWNER" to "ADVERTISER", otherwise leave it alone
  4. Remove the "runas" entry entirely (you don't need it)
  5. Set expiration to 3600 (one hour)

Now hit the "Execute" button! If all went well, you'll get a response that looks like this:

Congrats! You have managed to generate a login token. Copy the contents of the token field, and scroll up until you see the "Authorize" button near the top of the page. Hit that button, and in the value field enter:

Bearer (your token)

So, if your token was 1234abcd, you would put Bearer 1234abcd in the field, and press "Authorize", then hit "Done"

Testing the JWT token

Finally, test your login by expanding the GET /users/self endpoint, and hitting "Try it out", and "Execute". If you are not logged in, this endpoint won't work - but if you are, it should give you the contents of the JWT token that you just put into the authenticator.