Integration guide

Steps

Here are the endpoints Manifold requires a platform to implement in order to provide a secure, customizable, embedded marketplace user experience.

Identity profiles

Manifold creates a profile for each unique actor interacting with your embedded marketplace. The profile contains a mapping of your own identifier for this actor (subject), and Manifold’s internal identity (id).

NOTE: When interacting with Manifold APIs, you only ever need to use your proprietary identifier as the actor (e.g your own user ID value). Manifold will translate this for you.

Should you need to permanently and irrevocably change a Profile’s subject, you can use updateProfileSubject to change the underlying identifier used in our system. See our GraphQL API docs for mutation details.

Issuing an authentication token

Your platform is responsible for creating Manifold authentication tokens on a per-actor basis. This is done through our GraphQL API using the createProfileAuthToken mutation. See our GraphQL API docs for mutation details.

Profile information

We require on-demand access to profile information in order to satisfy our provider integrations and provide a customized user experience.

Additional information provided in this response is used to dictate provisioning behavior policies within the marketplace and assist in the prevention of abuse.

This endpoint will return information about any type of profile in the platform’s system, such as users and teams. When a profile is not associated with a user, we expect the platform to return profile-specific information - such as is_email_verified - for the owner of the profile. This implementation supersedes the OAuth2 UserInfo implementation.

URL Parameters

ParameterTypeDescription
idstringThe unique identifier for the profile, as stored within the platform’s system.

Request

GET /v1/profiles/:id HTTP/1.1
Host: https://<baseurl>
Content-Type: application/x-www-form-urlencoded
Accept-Encoding: gzip
Authorization: Bearer <platform_access_token>

Response

{
  id: string,
  country: ISO 3166-1 alpha-2,
  is_email_verified: bool,
  is_phone_verified: bool,
  is_2fa_enabled: bool,
  state: active|suspended|deleted,
  standing: good|delinquent|abuse,
  has_payment_method: bool,
  has_first_payment: bool
}
Parameter Type Description
id string The profile’s ID, as stored within the Platform’s system.
state string The current state of the profile, can be one of "active", "suspended" or "deleted"
country string Optional. ISO 3166-1 alpha-2 representation of the country associated with the user.
is_email_verified bool Optional. Has the profile’s email been verified or not? Defaults to false.
is_phone_verified bool Optional. Has the profile’s phone been verified or not? Defaults to false.
is_2fa_enabled bool Optional. Has the profile enabled 2 factor authentication or not? Defaults to false.
standing string Optional. The current financial standing of the profile. Can be one of "good", "delinquent" or "abuse".
has_payment_method bool Optional. Does the profile have a billing account linked or not? Defaults to false.
has_first_payment bool Optional. Has the profile made a payment before or not? Defaults to false.

Listing users in the context of a resource

We required the ability to identify which users have access to a given resource, within a stated annotation context. This endpoint helps Manifold understand the scope of access when it comes to a resource, and permits our service providers to understand teams and organizations of users.

Query Parameters

ParameterDescription
resource_idThe Manifold resource ID
owner_idA platform’s unique identifier for the resource owner
annotationsPipe-delimited annotation strings

Request

GET /v1/users HTTP/1.1
Host: https://<baseurl>
Content-Type: application/x-www-form-urlencoded
Accept-Encoding: gzip
Authorization: Bearer <platform_access_token>

Response

{
  "users": [ 
    { 
      "id":"XYZ1",
      "role":"admin",
      "name": "Jane Doe",
      "email": "jd@deer.com"
    },
    { 
      "id":"XYZ2",
      "role":"admin",
      "name": "Play Doe",
      "email": "pd@deer.com"
    }
  ]
}

Testing authorization

Manifold requires the ability to check with your platform for whether a specific action should be permitted within the marketplace. A resource is not always owned by the entity performing an action, and these permissions can change in real-time within your platform. We use this authorization test to ensure the actor still has permission to proceed.

Query Parameters

Parameter Type Description
actor_id string A platform’s unique identifier for the actor
owner_id string A platform’s unique identifier for the resource owner
verb string The action the actor is requesting to perform, one of: CREATE, READ, UPDATE, CHANGE_PLAN, SSO, DELETE, READ_CREDENTIALS, READ_INVOICE
priced bool Boolean of whether this action carries an impact on a user’s costs.
resource_ids string Optional. Pipe-delimited Manifold resource IDs
annotations string Optional. Pipe-delimited annotation strings

Request

GET /v1/resources/authorized HTTP/1.1
Host: https://<baseurl>
Content-Type: application/x-www-form-urlencoded
Accept-Encoding: gzip
Authorization: Bearer <platform_access_token>

Response

{
  “resources”: [
    {
      "authorized": true,
      "resource_id": "abc1234"
    },
    …
  ]
}