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

    Flex 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 Flex. What token needs to be passed to Flex, 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 Flex user account or if a verified email address resolved from the token matches a verified email address of a Flex 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

    {
      "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.