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

Parameter

Type

Description

id

string

The 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,
name: string,
email: string
}

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.

name

string

Optional. The name of the user this profile represents. May be required in order to integrate with some third-party providers.

email

string

Optional. The email of the user this profile represents. May be required in order to integrate with some third-party providers.

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

Parameter

Description

resource_id

The Manifold resource ID

owner_id

A platform’s unique identifier for the resource owner

annotations

Pipe-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"
},
]
}