Authentication API reference

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 four 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.
trusted:user	Provides access to Marketplace API resources that require a secure context.
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.
token_exchange	A grant that allows exchanging a user token to a trusted:user token using a client secret.

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.

Identity providers

Sharetribe supports external identity providers to be used when requesting an access token or when creating a new user. In order to authenticate a user using an identity provider, the user must first authenticate themselves in the identity provider. As a result of this, a token is obtained and passed to Sharetribe. What token needs to be passed to Sharetribe, depends on the identity provider.

Identity provider	IdP ID	IdP token
Facebook	facebook	(user) access token
Google	google	ID token
OpenID Connect	<custom ID>	ID token

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,
  "scope": "user",
  "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.

Trusted user access token

Parameter	Description
client_id	The API client ID of your Marketplace API application.
client_secret	The API client secret of your Marketplace API application.
subject_token	A valid user access token obtained with grant_type password.
grant_type	token_exchange The grant type used to obtain an access token.
scope	trusted: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.
scope	String with space-separated list of scopes associated with the access token.
refresh_token	(only when grant_type is password or client_credentials with a client_secret) The refresh token.

Issuing tokens with an identity provider

HTTP request

POST /v1/auth/auth_with_idp

Example request

$ curl -X POST 'https://flex-api.sharetribe.com/v1/auth/auth_with_idp'
    -H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
    -H 'Accept: application/json' \
    -d 'client_id=08ec69f6-d37e-414d-83eb-324e94afddf0&client_secret=5f840427-a1c3-4591-a887-aceef679cad8&idp_id=facebook&idp_client_id=11223344&idp_token=aabbccdd'

Example response

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

This endpoint can be used to request an access token by providing a token obtained from an external identity provider service where a user has authenticated themselves. Using this endpoint requires that a corresponding identity provider client has been configured for the marketplace. See identity provider clients in Console.

An access token is returned if idpToken can be verified and an identity provider account resolved from the token is associated with a Sharetribe user account or if a verified email address resolved from the token matches a verified email address of a Sharetribe user account.

If an access token is not returned, client implementations should show a message to the user accordingly or use the /current_user/create_with_idp endpoint in the Marketplace API to create a user account by passing the same idp_* parameters.

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.

User access token

Parameter	Description
client_id	The API client ID of your Marketplace API application.
client_secret	The client secret of your Marketplace API application.
idp_id	IdP ID of the identity provider client that is used to authenticate the user. See identity provider clients in Console.
idp_client_id	Client ID of the identity provider client that is used to authenticate the user. See identity provider clients in Console.
idp_token	Token obtained from an identity provider. See supported identity providers for more information on what token needs to be provided with a given identity provider.

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.
scope	String with space-separated list of scopes associated with the access token.
refresh_token	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

{
  "client-id": "08ec69f6-d37e-414d-83eb-324e94afddf0",
  "scope": "user",
  "exp": 1521545955
}

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.