External Identities API

Add and remove identities from Limio.

In this document, the end-user refers to a subscriber interacting with their subscription online. The Limio app user refers to you!

The External Identities API empower multiple end-users to seamlessly access self-service for the same subscription(s). This is especially beneficial in B2B scenarios, where an end-user might have originally purchased a subscription, however multiple end-user (owner, finance director, operations...) require the ability to change the subscription and process new purchases such as add-ons.

With these endpoints, Limio app user have a mechanism to allow multiple end-users to access the same subscription. Here’s what you need to know:

Access Control:

Currently, Limio operates on a flat-level access control system. This means each end-user granted access to the subscription will possess equivalent permissions to other end-users (including the original end-user who made the purchase).

Once a new end-user is added via the External Identity API, the end-user will be able to perform similar actions:

See all subscriptions
Modify payment methods
Cancel or switch between offers
Edit add-ons
View invoices

Endpoint Details:

At the point the user is trying to access the Limio Shop & Self-Service, you can use the following External Identity endpoint to authorize the access to the Limio Shop & Self-Service of new end-users:

https://{shard}.{domain}.limio.com/api/objects/externalidentity

The External Identity endpoint is designed to accept POST and DELETE HTTP methods for adding or removing end-users respectively. It expects a request body formatted as follows:

{
  "id_token": {
    "iss": "https://accounts.google.com",
    "sub": "123456789012345680000"
  }
}

Where iss represents the token's issuer and sub is the identifier for the subject user.

To associate the subscription(s) that this External Identity will have access to, Limio requires the following request headers:

The UID cookie. This cookie will be generated by Limio after an end-user goes through authentication within the Limio Shop & Self-Service. These will look e.g "Cookie: lmo_uid=eyJhbGciOiJSUzI1Ni....". The cookie is set after the user has logged into the Limio Shop & Self-Service.
The host header. This is the host Limio site, set as xLimioHost. This would be for example: "xLimioHost: yourLimioApp.prod.limio.com."

The UID allows Limio to identify the user who is requesting the change i.e employee 1 adding employee 2. The id_token would be required from the identity provider that is integrated within Limio i.e. the token the user would log into your native site with.

This endpoint is currently only available if externally implemented. Limio does not provide a mechanism within MMA to provide this functionality.

Example HTTP format of the request:

DELETE /api/objects/externalidentity HTTP/1.1
Host: localhost:9002
authorization: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2xvY2FsaG9zdDo4MDAzIiwiaWF0IjoxNjk3NjIxNDA5LCJleHAiOjE2OTc2MjUwMDksInN1YiI6ImlkLTZmMDczZjViZGUzMDg3ZmMwYjI1ZWQyOTQ0YzEwZDlkIiwiaHR0cHM6Ly9sb2NhbGhvc3Q6ODAwMy9hdXQiOnsiaXNzIjoiaHR0cHM6Ly9jb2duaXRvLWlkcC5ldS1jZW50cmFsLTEuYW1hem9uYXdzLmNvbS9ldS1jZW50cmFsLTFfc093R1h3NVF3Iiwic3ViIjoiMzEzZmEzZmQtZjVmZS00YmQ5LWIwMGUtZTY1NTc5MjYyMjFiIn0sImxtbzp1c3QiOjEsImVtYWlsX3ZlcmlmaWVkIjp0cnVlfQ.aXW8SiYqrCkkXseZf3UO3tEJLaHlF9RXJ_nADAOX2GIuwx6Jb9_Cc_MdNaNC7IVoBVvNBNZWA4u7qmj4946zpRTYrBgd-eeR-9ed1PkNrtPrY57PiLkdaIOcUn5-VB_FH9O3gwN4AHtbAZDZOgsskf60985t0krqeEXsM0X_-G-Di0B5f2NTZiAOxL3UY6022hq7DjbcNnGrAQYRvhIHIKe3hKIaKcP83HyyEt-AoJGY9V7l8URfnRtbwEmyEEjNRrvTksRsWI1Y8mH7x_kfzcTctbicAzhRursDNbpmG6PxRd8WzP9HCzgelZA7rn_2nhs7q3fs7GiSIUq0zKmVoQ
x--limio-app: shop
x--limio-host: domain.prod.limio.com
cookie: lmo_ls=e30%3D.k3qNVOx%2BlZTYHZNjZTz96eCa%2BGHIr%2BD%2BO5%2Fwv%2BRMIvY%3D; limio-country=GB; limio-lmo_uid=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2xvY2FsaG9zdDo4MDAzIiwiaWF0IjoxNjk3NjIxNDA5LCJleHAiOjE2OTc2MjUwMDksInN1YiI6ImlkLTZmMDczZjViZGUzMDg3ZmMwYjI1ZWQyOTQ0YzEwZDlkIiwiaHR0cHM6Ly9sb2NhbGhvc3Q6ODAwMy9hdXQiOnsiaXNzIjoiaHR0cHM6Ly9jb2duaXRvLWlkcC5ldS1jZW50cmFsLTEuYW1hem9uYXdzLmNvbS9ldS1jZW50cmFsLTFfc093R1h3NVF3Iiwic3ViIjoiMzEzZmEzZmQtZjVmZS00YmQ5LWIwMGUtZTY1NTc5MjYyMjFiIn0sImxtbzp1c3QiOjEsImVtYWlsX3ZlcmlmaWVkIjp0cnVlfQ.aXW8SiYqrCkkXseZf3UO3tEJLaHlF9RXJ_nADAOX2GIuwx6Jb9_Cc_MdNaNC7IVoBVvNBNZWA4u7qmj4946zpRTYrBgd-eeR-9ed1PkNrtPrY57PiLkdaIOcUn5-VB_FH9O3gwN4AHtbAZDZOgsskf60985t0krqeEXsM0X_-G-Di0B5f2NTZiAOxL3UY6022hq7DjbcNnGrAQYRvhIHIKe3hKIaKcP83HyyEt-AoJGY9V7l8URfnRtbwEmyEEjNRrvTksRsWI1Y8mH7x_kfzcTctbicAzhRursDNbpmG6PxRd8WzP9HCzgelZA7rn_2nhs7q3fs7GiSIUq0zKmVoQ; lmo_session=DkjZmyAtHcYAWhhlCBbjhG7NMuqsqjcD
x--limio-mode: production
Content-Type: application/json
Content-Length: 72

{
    "id_token": {
        "iss": "https://accounts.google.com",
        "sub": "123456789012345680000"
    }
}

Add external identity

This API can be used to add an external identity to an existing Limio identity. This can be used in this case where an organisation wants to purchase multiple subscriptions for their employees, and they want to link their existing Limio identity to their organisation's identity.

POSThttps://your-environment.prod.limio.com/api/objects/externalidentity

Authorization

Header parameters

Body

id_tokenobject

id_token

Response

Body

namestring

dataobject

statusstring

record_typestring

record_variantstring

ownerstring

idstring

servicestring

createdstring

updatedstring

modestring

Request

const response = await fetch('https://your-environment.prod.limio.com/api/objects/externalidentity', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

{
  "name": "John Doe",
  "data": {
    "iss": "https://domain.com",
    "sub": "sub"
  },
  "status": "active",
  "record_type": "identity",
  "record_variant": "@limio/external-id",
  "owner": "123456789012345678901",
  "id": "12345678901234564923810",
  "service": "limio",
  "created": "2021-01-01T00:00:00.000Z",
  "updated": "2021-01-01T00:00:00.000Z",
  "mode": "production"
}

Remove external identity

Remove an external identity from an existing Limio identity

DELETEhttps://your-environment.prod.limio.com/api/objects/externalidentity

Authorization

Body

id_tokenobject

id_token

Response

Body

RemoveExternalIdentityResponse (object)

Request

const response = await fetch('https://your-environment.prod.limio.com/api/objects/externalidentity', {
    method: 'DELETE',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

{}

Further documentation available: https://api.limio.com/#tag/Identities

Operational Criteria:

To maintain integrity and avoid duplication, the system is designed with specific constraints:

Existing Limio end-users cannot be reassigned to an additional subscription.
Deletion requests must originate from the same overarching subscription; otherwise, the request will be denied.

If there are any issues please reach out to Limio Support.

PreviousUsing the Shop Build & Publish API NextUsing Webhooks

Last updated 1 month ago