Identity providers

Identity providers

Identity providers (IDPs) are used in conjunction with Single Sign-On (SSO) SAML2 to authenticate users. As such, you will need to make sure SSO is included in your account/package to make use of identity providers.

Often you will only have one identity provider. However for larger organisations you may authenticate your employees using alternative systems.

You can manage your identity providers by making the following requests:

RequestDescription
GET /idpsReturn the details of all of the identity providers in your account
GET /idps/:idReturn the details of a single identity provider
PATCH /idps/:idUpdate an identity provider
DELETE /idps/:idDelete an identity provider
POST /idpsCreate an identity provider

GET /idps

Return the details of all of the identity providers in your account.

Example request

curl \
-H "Authorization: Bearer YOUR-API-KEY" \
"https://api.vidbeo.com/v2/idps"

Example response

{
"success": true,
"result": [
{
"id": "abcde12345abcde12345a",
"name": "Example idp",
"company": "other",
"type": "saml2",
"certificate": "MII...",
"entity_id": "https://example.com",
"signin_url": "https://example.com",
"digest_algorithm": "sha256",
"signature_algorithm": "sha256",
"created_by": "abcde12345abcde1234a",
"created_time": "2021-02-01T00:00:00.000Z",
"updated_by": "abcde12345abcde12345a",
"updated_time": "2021-02-01T00:00:00.000Z"
},
...
],
"links": {},
"errors": []
}

Optional parameters

NameTypeDefaultInformation
limitString25Maximum number to return
cursorString""Used to get the next page of results: if applicable we return this as part of the links.next URL

GET /idps/:id

Return the details of a single identity provider.

Example request

curl \
-H "Authorization: Bearer YOUR-API-KEY" \
"https://api.vidbeo.com/v2/idps/abcde12345abcde12345a"

Example response

{
"success": true,
"result": {
"id": "abcde12345abcde12345a",
"name": "Example idp",
"company": "other",
"type": "saml2",
"certificate": "MII...",
"entity_id": "https://example.com",
"signin_url": "https://example.com",
"digest_algorithm": "sha256",
"signature_algorithm": "sha256",
"created_by": "abcde12345abcde1234a",
"created_time": "2021-02-01T00:00:00.000Z",
"updated_by": "abcde12345abcde12345a",
"updated_time": "2021-02-01T00:00:00.000Z"
},
"links": null,
"errors": []
}

Response format

KeyTypeDescription
idStringThe unique identifier given to this idp
nameStringThe name given to this idp
companyStringThe company name, used to assign a logo/icon in the UI. May be 'other'
typeStringCurrently only 'saml2' IDPs are supported
certificateStringThe public certificate the IDP will provide
entity_idStringThe entity ID your application uses
signin_urlStringThe URL the IDP expects SAML2 requests to be POSTed to
digest_algorithmStringCurrently only the standard 'sha256' is supported
signature_algorithmStringCurrently only the standard 'sha256' is supported
created_byStringThe ID of the user who created it (if known)
created_timeStringThe date and time it was created
updated_byStringThe ID of the user who last modified it (if known)
updated_timeStringThe date and time it was last modified

PATCH /idps/:id

Update an identity provider.

The body of the request should contain one, or more, attributes that you would like to update for the idp. Please be careful when making changes to existing items to avoid losing data, particularly if a particular key has sub-keys.

Example request

curl \
-g \
-H "Authorization: Bearer YOUR-API-KEY" \
-H "Content-Type: application/json" \
-X PATCH \
-d '{"name":"New name"}' \
"https://api.vidbeo.com/v2/idps/abcde12345abcde12345a"

Example response

{
"success": true,
"result": {
"id": "abcde12345abcde12345a",
"name": "New name",
"company": "other",
"type": "saml2",
"certificate": "MII...",
"entity_id": "https://example.com",
"signin_url": "https://example.com",
"digest_algorithm": "sha256",
"signature_algorithm": "sha256",
"created_by": "abcde12345abcde1234a",
"created_time": "2021-02-01T00:00:00.000Z",
"updated_by": "abcde12345abcde12345a",
"updated_time": "2021-02-01T00:00:00.000Z"
},
"links": null,
"errors": []
}

DELETE /idps/:id

Delete an identity provider.

Example request

curl \
-H "Authorization: Bearer YOUR-API-KEY" \
-X DELETE \
"https://api.vidbeo.com/v2/idps/abcde12345abcde12345a"

Example response

{
"success": true,
"result": {},
"links": null,
"errors": []
}

POST /idps

Create an identity provider.

Example request

curl \
-g \
-H "Authorization: Bearer YOUR-API-KEY" \
-H "Content-Type: application/json" \
-X POST \
-d '{"name":"Google", "company":"google", "type":"saml2"}' \
"https://api.vidbeo.com/v2/idps"

Example response

{
"success": true,
"result": {
"id": "abcde12345abcde12345a",
"name": "Google",
"company": "google",
"type": "saml2",
"certificate": "",
"entity_id": "",
"signin_url": "",
"digest_algorithm": "sha256",
"signature_algorithm": "sha256",
"created_by": "abcde12345abcde1234a",
"created_time": "2021-02-01T00:00:00.000Z",
"updated_by": "abcde12345abcde12345a",
"updated_time": "2021-02-01T00:00:00.000Z"
},
"links": null,
"errors": []
}

Required parameters

The required parameters: a name for the identity provider, a value for company to show a logo/icon (if not sure, use 'other'), and a type of 'saml2' (the only supported type for now).

KeyTypeDescription
nameStringThe name of the idp (1-100 characters)
companyStringA lowercase string to show a logo by its name in the UI
typeStringCurrently only 'saml2' is supported for the IDP's type

Optional parameters

KeyTypeDescription
certificateStringThe public certificate the IDP will provide
entity_idStringThe entity ID your application uses
signin_urlStringThe URL the IDP expects SAML2 requests to be POSTed to

Creating the IDP will add it to the database. However for it to be usable you will still need to provide the three optional parameters via a subsequent PATCH /idps/:id if not initially provided. Since our system needs the signin_url to know where to send (POST) SSO requests from your users, and we need the entity_id and certificate to verify SSO responses from your IDP. You should be able to get all those values from your IDP.