Connector API

The Connector API allows Providers to query Manifold for data related to provisioned resources and users of those resources.

It can be used for the following things:

  • To verify a user coming in from SSO
  • To get information about that user
  • To get information about resources provisioned from your product
  • To get information about who currently ownss and/or has access to those resources (Name & email)

Available at https://api.connector.manifold.co.

Fully detailed in its OpenAPI specification.

Authentication

An OAuth 2.0 Bearer Token is used to authenticate with the Connector API. An access token is granted to you either by yourself or by a user as part of the SSO flow.

Requests that require authentication will return 401 Unauthorized. If the requester has insufficient access, a 404 Not Found may be returned instead of a 401 Unauthorized. This is to prevent the accidental leakage of private data. Access Tokens are valid for 24 hours.

OAuth Credentials are given to you by us and are scoped to a specific product in our catalog. All granted access tokens are scoped to the product's credentials. To acquire a set of OAuth Credentials please contact Manifold Support.

OAuth

For a complete API reference, click here.

Create Access Token

You use this endpoint to acquire a scoped access token which grants you the authority to act on behalf of the grantor (either you or user) of the token.

There are two grant types used for requesting an access token:

  • authorization_code, which allows you to exchange a code granted by a user for an access token, giving you permission to act on the user's behalf.
  • client_credentials, which allows you to grant yourself an access token scoped to a product.

This endpoint is a part of the SSO flow invoked by users when attempting to navigate to a product's dashboard. A code is only valid for five minutes and cannot be used more than once to grant an access token.

Provider authentication is supported with client_id and client_secret in either the request body, or via basic authentication. Basic authentication is the preferred method, but is not required.

The granted access token will expire within 24 hours.

Current Identity

You can call this endpoint to return the identity represented by the access token. Depending on the grant type used to create an access token, the underlying identity will be different.

Grant Type -> Identity Type authorization_code -> user client_credentials -> product

Get list of OAuth credentials without secrets

This lists all non-expired OAuth 2.0 credential pairs for your product. This does not return the secret.

Create an OAuth credential pair

This creates an OAuth 2.0 credential pair for your product. client_secret is stored as a scrypt hash only; if the value is lost after creation, it cannot be recovered.

Delete an OAuth credential pair

This deletes an OAuth 2.0 credential pair for a provider's product.

Resource

For a complete API reference, click here.

Retrieve a Resource

You can call this endpoint to return information about a specific resource.

The product and plan are the machine-readable labels which map to Product and Plan data inside our catalog. The product is globally unique while the plan is unique to the product. The region is the machine-readable representation of the platform and location in which this resource has been provisioned.

List All Users

You can call this endpoint to return a list of all users who have access to a specific resource.

None of this data should be stored as it's non-unique and will change. Instead, you can call this end-point to fetch the latest data.

Callback

For a complete API reference, click here.

Complete Request

You can call this endpoint to complete a request that had been acknowledged but not completed during the initial request as a part of a provision, plan change, or deprovision flow of a resource or credential.

If the Connector API can't be reached or an unexpected response is returned (for instance, 500 Internal Server Error), you should attempt to invoke the callback in the future until you get an expected response.

The behaviour of this route matches the "Repeatable Actions" specification of the Provider API. If the callback has already been received with the payload matching the previous request a 204 No Content response will be returned. However, if the payloads do not match the route will return a 409 Conflict error response.

If you’re responding to a request to provision credentials, then a hash of credentials must be provided. Otherwise, the credentials property must not be provided.

In the case of a credential provisioning callback, multiple key-value pairs that represent this set of credentials. However, if an URL form exists (e.g. postgres://user:pw@host:5432/db), please provide the credentials in that form.