Authentication API

Requests to the Marketplace API and the Integration API are authenticated using the Authentication API. It follows the OAuth2 framework.

Token types

The Authentication API uses tokens to authenticate requests. There are two types of tokens:

Token type	Description
access token	An access token is used to authenticate requests. Access tokens are typically valid for a short amount of time.
refresh token	A refresh token is issued when a user or an application successfully authenticates to the Authentication API. They are long lived and can be used as a "session secret". Refresh tokens can be used to issue fresh valid access tokens for the authenticated user or application.

Furthermore, the access tokens can be divided into three categories:

Access token	Description
anonymous	Provides anonymous access to the public resources in the Marketplace API. A fresh anonymous token can be obtained using your client ID.
user	Provides access to the Marketplace API as an authenticated marketplace user. A fresh access token can be obtained using a valid refresh token.
integration	Provides authenticated access to the Integration API. A fresh access token can be obtained using a valid refresh token.

Grant types

Access tokens are obtained through grants. The API supports the following types of grants:

Grant type	Description
client_credentials	A grant that can be used to obtain access tokens based on the application's own credentials. For Marketplace API applications, only the (public) client ID is required and an anonymous access token is granted. For Integration API applications, both the client ID and the client secret are required and the grant issues an integration access token, as well as a refresh token.
password	A grant that provides access as an authenticated marketplace user. Provides also a refresh token.
refresh_token	A grant that issues fresh access token given a valid refresh token.

Content types

The Authentication API requires that all POST requests are sent as application/x-www-form-urlencoded. All responses are application/json.

Errors

Observe the HTTP status code of the response to determine whether the request was successful.

HTTP status code	Description
200	Success
400	Bad request. The request was malformed, a mandatory parameter was missing or was invalid.
401	Unauthorized. The authentication was not successful. The credentials are invalid or expired.

API endpoints

Issuing tokens

HTTP request

POST /v1/auth/token

Example request

$ curl -X POST 'https://flex-api.sharetribe.com/v1/auth/token'
    -H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
    -H 'Accept: application/json' \
    -d 'client_id=08ec69f6-d37e-414d-83eb-324e94afddf0&grant_type=password&username=user%40example.com&password=secret&scope=user'

Example response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtYXJrZXRwbGFjZS1pZCI6IjE2YzZhNGI4LTg4ZWUtNDI5Yi04MzVhLTY3MjUyMDZjZDA4YyIsImNsaWVudC1pZCI6IjA4ZWM2OWY2LWQzN2UtNDE0ZC04M2ViLTMyNGU5NGFmZGRmMCIsInRlbmFuY3ktaWQiOiIxNmM2YTRiOC04OGVlLTQyOWItODM1YS02NzI1MjA2Y2QwOGMiLCJzY29wZSI6InVzZXIiLCJleHAiOjE1MjE0NDk0MTMsInVzZXItaWQiOiIzYzA3M2ZhZS02MTcyLTRlNzUtOGI5Mi1mNTYwZDU4Y2Q0N2MiLCJ1c2VyLXJvbGVzIjpbInVzZXIucm9sZS9wcm92aWRlciIsInVzZXIucm9sZS9jdXN0b21lciJdfQ.UQtQ9dUbyiM0x0DSKbzqBU39Ei_9UK4vfubKcIB1aS4",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "75ec1d28-5427-4425-8fde-1fd49550aa71--615adbf9-1abb-49f3-84ae-97f5d4977d3f"
}

Body parameters

The request body should be sent as application/x-www-form-urlencoded. The set of required parameters and their accepted values vary based on the type of access token that is being issued.

Anonymous access token

Parameter	Description
client_id	The API client ID of your Marketplace API application.
grant_type	`client_credentials` Grant type that is used.
scope	`public-read` The scope of the access token.

User access token

Parameter	Description
client_id	The API client ID of your Marketplace API application.
grant_type	`password` or `refresh_token` The grant type used to obtain an access token.
username	(only when `grant_type` is `password`) The username (email address) of the user.
password	(only when `grant_type` is `password`) The password of the user.
refresh_token	(only when `grant_type` is `refresh_token`) The refresh token.
scope	`user` The Scope of the access token.

Integration access token

Parameter	Description
client_id	The API client ID of your Integration API application.
grant_type	`client_credentials` or `refresh_token` The grant type used to obtain an access token.
client_secret	(only when `grant_type` is `client_credentials`) The client secret of your Integration API application.
refresh_token	(only when `grant_type` is `refresh_token`) The refresh token.
scope	`integ` The scope of the access token.

Response format

The response is JSON object with following attributes:

Attribute	Description
access_token	The issued access token, depending on the grant type.
token_type	Always `bearer`
expires_in	Number of seconds for which the access token is valid.
refresh_token	(only when `grant_type` is `password` or `client_credentials` with a `client_secret`) The refresh token.

Revoking a refresh token

HTTP request

POST /v1/auth/revoke

Example request

$ curl -X POST 'https://flex-api.sharetribe.com/v1/auth/revoke
    -H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
    -H 'Accept: application/json' \
    -d 'token=75ec1d28-5427-4425-8fde-1fd49550aa71--615adbf9-1abb-49f3-84ae-97f5d4977d3f'

Example response

{
  "revoked": true
}

Body parameters

Parameter	Description
token	The refresh token.

Response format

The response is always a JSON object with attribute revoked set to true.

Getting details for a token

HTTP request

GET /v1/auth/token

Example request

$ curl -X GET 'https://flex-api.sharetribe.com/v1/auth/token'
    -H 'Accept: application/json' \
    -H 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtYXJrZXRwbGFjZS1pZCI6IjE2YzZhNGI4LTg4ZWUtNDI5Yi04MzVhLTY3MjUyMDZjZDA4YyIsImNsaWVudC1pZCI6IjA4ZWM2OWY2LWQzN2UtNDE0ZC04M2ViLTMyNGU5NGFmZGRmMCIsInRlbmFuY3ktaWQiOiIxNmM2YTRiOC04OGVlLTQyOWItODM1YS02NzI1MjA2Y2QwOGMiLCJzY29wZSI6InVzZXIiLCJleHAiOjE1MjE0NDk0MTMsInVzZXItaWQiOiIzYzA3M2ZhZS02MTcyLTRlNzUtOGI5Mi1mNTYwZDU4Y2Q0N2MiLCJ1c2VyLXJvbGVzIjpbInVzZXIucm9sZS9wcm92aWRlciIsInVzZXIucm9sZS9jdXN0b21lciJdfQ.UQtQ9dUbyiM0x0DSKbzqBU39Ei_9UK4vfubKcIB1aS4'

Example response

{
  "marketplace-id": "16c6a4b8-88ee-429b-835a-6725206cd08c",
  "client-id": "08ec69f6-d37e-414d-83eb-324e94afddf0",
  "tenancy-id": "16c6a4b8-88ee-429b-835a-6725206cd08c",
  "scope": "user",
  "exp": 1521545955,
  "user-id": "3c073fae-6172-4e75-8b92-f560d58cd47c",
  "user-roles": [
    "user.role/provider",
    "user.role/customer"
  ]
}

The request must contain access token in the Authorization header.

Response format

Attribute	Description
client-id	The ID of the client that this token was issued to.
scope	String with space-separated list of scopes associated with this token.
exp	The unix timestamp (integer timestamp, number of seconds since January 1, 1970 UTC) indicating when this token will expire.