External Identities API

Add and remove identities to a Limio Customer.

The External Identities API empower multiple end-users to seamlessly access Limio 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, access invoices, and process new purchases such as add-ons.

With this endpoint, developers and integrators have a mechanism to add multiple end-users to access the same subscription(s) while maintaining the safety of the data.

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

Pre-requisite:

To use this API, you will need:

• A Limio Subscription with an existing end-user (User 1) related to your Identity Platform

  • This Limio Subscription may be created via a Limio Order. It could also be migrated into Limio.

• The lmo_uid cookie generated by Limio for the existing end-user (User 1)

  • lmo_uid will be generated as part of accessing an authenticated page in Limio, typically during the initial purchase via a Limio authenticated checkout.

  • lmo_uid can also be re-generated by silently redirecting User 1 to any Limio authenticated page.

• A shared top domain between your application (e.g. saas.domain.com) and the Limio custom domain used for Limio Self-Service (e.g. billing.domain.com)

Use case:

When User 1 is in your application (saas.domain.com) and navigate to the User Management section, they may create or set that User 2 should have access to Limio Self-Service.

When User 2 is set to have this access, you should call the Limio External Identity API to add their identity to User 1's Limio Subscription(s).

To do that, you would call the following endpoint using a bearer token:

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

With the following request headers:

• The lmo_uid cookie of User 1: These will look e.g "Cookie: lmo_uid=eyJhbGciOiJSUzI1Ni....". The cookie is set after User 1 has accessed any authenticated page in Limio Shop or Limio Self-Service. The cookie is what enables Limio to identifies User 1's related Limio Subscription(s).

• The host header: This is the host Limio site, set as xLimioHost. This would be for example: "xLimioHost: yourLimioApp.prod.limio.com."

Posting the following request body:

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

Where:

• iss represents the token's issuer from your Identity Provider (e.g. AWS Cognito, Salesforce, Auth0, Okta...)

• sub is the identifier for the subject user.

Here is an example in HTTP format of the API 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"
    }
}

Note:

• This endpoint is currently only available if externally implemented from your application. Limio does not provide a mechanism within Limio Self-Service to add a user.

• The External Identity endpoint is designed to accept POST and DELETE HTTP methods for adding or removing end-users respectively.

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.

post

/objects/externalidentity

Authorizations

Header parameters

Cookiestringrequired

Cookie including lmo_uid is required

Example: lmo_uid=your_cookie_value

xLimioHoststringrequired

xLimioHost domain is required

Example: your.domain.com

Body

id_tokenobject

id_token

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://your-environment.prod.limio.com/api/objects/externalidentity' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Cookie: lmo_uid=your_cookie_value' \
  --header 'xLimioHost: your.domain.com' \
  --header 'Content-Type: application/json' \
  --data '{
    "id_token": {
      "iss": "https://domain.com",
      "sub": "sub"
    }
  }'

200

401

404

200

{
  "name": "John Doe",
  "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",
  "data": {
    "iss": "https://domain.com",
    "sub": "sub"
  }
}

OK

Remove external identity

Remove an external identity from an existing Limio identity

delete

/objects/externalidentity

Authorizations

Body

id_tokenobject

id_token

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request DELETE \
  --url 'https://your-environment.prod.limio.com/api/objects/externalidentity' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "id_token": {
      "iss": "https://domain.com",
      "sub": "sub"
    }
  }'

200

401

404

502

200

{}

OK

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.