Links

Authentication

To get access to the API, first make sure you have signed up as a Partner on the Dashboard.
Swan uses OAuth2 and Bearer authentication to authenticate you and your users to the API.

About OAuth2

OAuth2 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 OAuth2, see oauth.net and RFC 6749.

About Bearer authentication

Bearer authentication (also called token authentication) is an HTTP authentication scheme that uses access tokens. The access token is a cryptic string generated by Swan in response to an OAuth2 authorization request. You can use the token 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

Token expiration

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 an invalid grant or authentication failure with the HTTP status code 401 Unauthorized, and you'll need to request a new access token.

User access tokens

  • Allow you to act on behalf of an individual user.
  • Must use the authorization code OAuth2 flow (also referred to as grant type).

Project access tokens

  • Allow you to act on your own behalf rather than on behalf of a user.
  • Allow you to act as a user within your project, sometimes referred to as impersonation.
  • Must use the client credentials OAuth2 flow (also referred to as grant type), intended for server-to-server authentication.