NAV Navbar
curl
  • Authentication API
  • Token types
  • Grant types
  • Content types
  • Errors
  • API endpoints
  • 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 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.

    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.

    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.