Authentication

To get access to the API, first make sure you have signed up as a partner in our dashboard.

Swan uses OAuth 2.0 and Bearer authentication to authenticate you and your users to the API.

OAuth 2.0 is an authorization protocol that gives an API client limited access to user data on a web server. Notably, GitHub, Google, and Facebook APIs use it. OAuth relies on authentication scenarios called flows, which allow the resource owner to share the protected content from the resource server without sharing their credentials.

For more information about OAuth 2.0, see oauth.net and RFC 6749

Bearer authentication (also called token authentication) is an HTTP authentication scheme that involves security tokens called access tokens. The access token is a cryptic string generated by Swan in response to an OAuth 2.0 authorization request that you can use to access protected resources on behalf of the resource owner.

The Bearer authentication scheme was created as part of OAuth 2.0 in RFC 6750

The access token is provided through the HTTP Authorization header, such as Authorization: Bearer {access token}, and is valid for a limited time. When an access token has expired, the API call will return the HTTP status code 401 Unauthorized and a new access token has to be acquired.

Access Tokens

  • User access token: These are used when you act on behalf of an individual user. To get a user access token, you have to use the OAuth2 flow (also called grant type): Authorization code. It's totally similar to how users log in to a web application using their Facebook or Google account.

  • Project access token: These are used when you act on your own behalf rather than on behalf of a user. To get a project access token, you have to use the OAuth2 flow (also called grant type): Client Credentials. This flow describes an approach when you intend for server-to-server authentication.