NAV Navbar
curl
  • Authentication API
  • Content types
  • Errors
  • API endpoints
  • Authentication API

    Every call to the Marketplace API must be made with a valid access token. API clients can obtain access tokens via the Authentication API.

    There are two types of tokens:

    Token type Description
    access token An access token is used to authenticate requests to the Marketplace API. Access tokens are typically valid for short amount of time.
    refresh token A refresh token is issued when marketplace users successfully authenticate 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.

    There are two kinds of access tokens:

    Access token Description
    anonymouns 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.

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

    Grant type Description
    client_credentials A grant that provides anonymous access based on valid (public) client ID. Can be used to issue anonymous access tokens.
    password A grant that provides access as an authenticated marketplace user. Can be used to issue refresh tokens.
    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

    TODO

    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.

    Parameter Description
    client_id The API client ID you have been assiged.
    grant_type One of client_credentials, password or refresh_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 Must be public-read when client_credentials grant is used or user when password or refresh_token grants are used.

    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) The refresh token.

    Revoking a refresh token

    TODO

    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
    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) The refresh token.