Credentials

On Manifold a Credentials represent the values Manifold users use to access a provisioned resource. In this document we'll walk through the requests necessary to creating and deleting Credentials.

The primary actions your integration will implement are:

  • Credential provisioning: PUT /v1/credentials/:id
  • Credential deprovisioning: DELETE /v1/credentials/:id

Always refer to the Provider API documentation for full API reference and definitions of advanced scenarios which Manifold supports.

Credential rotation testing

The Grafton credential rotation tests ensure that the Credentials endpoints can be used to perform a rotation. Credential rotation is a process managed by Manifold which results in a new credential being consumed by the end user in place of the initial one.

Depending on your service, you might need to support having multiple credentials per resource or you might only be supporting a single credential at a time per resource. Knowing this will allow you to tell Grafton which strategy to use. By default, Grafton defaults to multiple credential support.

Here are the different credential rotation strategies used by Grafton and how to change the one Grafton will use:

StrategySupportDescriptionGrafton Flag
Swap
(default)
MultipleA new credential is created first, and then the old one gets deleted
--credential multiple
ReplaceSingleThe initial credential is deleted first, and then a new one is created in its place.
--credential single

Credential provisioning request

Manifold calls this endpoint to request the provisioning of a credential. Manifold provisions resources and credentials separately to offer advanced features to its users like credential rotations and multiple credentials management.

Detailed information on this request can be found in the Provider API documentation.

Example Request

PUT /v1/credentials/268jhf1ppzjhb1mkcezhxuqzth6y6
X-Signature: L5sBInztA2FMUvDaiHlGze5Ocrd0P8-6oG7zWPDkK8UuxcNZ3PjT6IL-1N-7g-Vhonqy1sqxsi9CCKALzzTRAw RGMkX3O_z5jVrQhy9UteLydfEQaUD8WDurbEVZkWxHc fDdIKAxrdJoJQUbwnbRPBnsEjlvlMXsgIFKor-OgXGarZ_Y5yNm9G7nObQgKsWPBJxiHwPW4X5ihOELUfekcCg
Content-Type: application/json
Accept: application/json
{
  "id": "268jhf1ppzjhb1mkcezhxuqzth6y6",
  "resource_id": "268613uqpx8u9yrypjxvx1qtfrevc"
}

Example Response

HTTP/1.1 201 Created
Content-Type: application/json
{
  message: "Credentials created",
  credentials: {
    "SECRET": "value"
  }
}

Example Implementation (Node.js)

This code is taken directly from the Node.js Sample Provider.

server.put("/v1/credentials/:id", verifyMiddleware, function(req, res, next) {
  var resource = db.resources[req.body.resource_id];
  if (!resource) {
    res.statusCode = 404;
    return res.json({ message: "no such resource" });
  }
  db.credentials[req.params.id] = req.body;

  res.statusCode = 201;
  res.json({
    message: "Credentials created",
    credentials: {
      SECRET: "value"
    },
  });
});

Examples are also available in other programming languages:

We support more languages in our Authentication libraries and SDKs.

Testing

Using Grafton you can generate requests against your integration to validate your Credential provisioning API handler.

Here is how you would run Grafton to generate the example Manifold request:

$ grafton test \
   --region='all::global' \
   --client-id=21jtaatqj8y5t0kctb2ejr6jev5w8 \
   --client-secret=3yTKSiJ6f5V5Bq-kWF0hmdrEUep3m3HKPTcPX7CdBZw \
   --plan-features='{"age":2,"hat_color":"red","ready":true}' \
   --plan=ursa-minor \
   --new-plan=ursa-major \
   --connector-port=3001 \
   --product=bear \
   http://localhost:8080

ℹ️ You can ignore credential rotation tests until you've implemented deprovisioning of credentials.

Now, if you have followed the steps in order, the Grafton output should start to have a majority of passing tests.

Here is the expected Grafton output:

Grafton output provisioning credentials

Credential deprovisioning request

Manifold calls this endpoint to request the deprovisioning of a credential. Detailed information on this request can be found in the Provider API documentation.

Example Request

DELETE /v1/credentials/268jhf1ppzjhb1mkcezhxuqzth6y6
X-Signature: L5sBInztA2FMUvDaiHlGze5Ocrd0P8-6oG7zWPDkK8UuxcNZ3PjT6IL-1N-7g-Vhonqy1sqxsi9CCKALzzTRAw RGMkX3O_z5jVrQhy9UteLydfEQaUD8WDurbEVZkWxHc fDdIKAxrdJoJQUbwnbRPBnsEjlvlMXsgIFKor-OgXGarZ_Y5yNm9G7nObQgKsWPBJxiHwPW4X5ihOELUfekcCg
Content-Type: application/json
Accept: application/json
# No Request Body

Example Response

HTTP/1.1 204 No Content
Content-Type: application/json
# No Response Body

Example Implementation (Node.js)

This code is taken directly from the Node.js Sample Provider.

server.del("/v1/credentials/:id", verifyMiddleware, function(req, res, next) {
  var credential = db.credentials[req.params.id];
  if (!credential) {
    res.statusCode = 404;
    return res.json({ message: "no such credential" });
  }
  delete db.credentials[req.params.id];

  res.statusCode = 204;
  res.end();
});

Examples are also available in other programming languages:

We support more languages in our Authentication libraries and SDKs.

Testing

Run the Grafton test command used when testing the provisioning of a Credential above. Here is the expected Grafton output:

Grafton output deprovisioning credentials