Identity Service API

API Endpoint

Terminology

Utility Endpoints

In addition to the API, the following utility endpoints are available:

  • /health - Health-check page.

  • /health/fault - Purposefully generate a fault page (for diagnostics).

  • Home - Page showing the API name.

Clients

Clients

POST /clients
RequestsCreate client
Headers
Content-Type: application/vnd.api+json
Authorization: bearer <access_token>
Body
{
  "data": {
    "type": "clients",
    "attributes": {
      "label": "My client",
      "confidential": true,
      "redirect_url": ""
    }
  }
}
Responses200400401403500
Headers
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "clients",
    "id": "fbd71de5-5674-42f6-a66a-4e05e7c861ed",
    "attributes": {
      "label": "My client",
      "confidential": true,
      "redirect_url": "",
      "secret": "<some secret key string>",
      "created": "2016-10-03T15:16:29.643Z",
      "updated": "2016-10-03T15:16:29.643Z"
    },
    "relationships": {
      "createdBy": {
        "data": {
          "id": "7fb24232-c4dc-4a90-aef8-ba5d48ca406e",
          "type": "users"
        }
      },
      "groups": {
        "data": []
      },
      "updatedBy": {
        "data": {
          "id": "7fb24232-c4dc-4a90-aef8-ba5d48ca406e",
          "type": "users"
        }
      }
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "status": 400,
  "errorMessage": "Fault"
}
Headers
Content-Type: application/json
Body
{
  "status": 401,
  "errorMessage": "Not allowed: Authentication failed.",
  "developerMessage": "auth_violation"
}
Headers
Content-Type: application/json
Body
{
  "status": 403,
  "errorMessage": "Not allowed: Forbidden, no permission to access.",
  "developerMessage": "auth_violation"
}
Headers
Content-Type: application/json
Body
{
  "status": 500,
  "errorMessage": "An error message"
}

Create a client
POST/clients

Create a client.

Requires permission IDENTITY:FUNCTIONAL:CLIENT:CREATE

PUT /clients
RequestsUpdate security group
Headers
Content-Type: application/vnd.api+json
Authorization: bearer <access_token>
Body
{
  "data": {
    "type": "clients",
    "id": "00000000-0000-0000-0000-000000000000",
    "attributes": {
      "label": "My Label",
      "redirect_url": "http://example.com"
    }
  }
}
Responses200400401403404500
Headers
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "clients",
    "id": "fbd71de5-5674-42f6-a66a-4e05e7c861ed",
    "attributes": {
      "label": "My client",
      "confidential": true,
      "redirect_url": "",
      "created": "2016-10-03T15:16:29.643Z",
      "updated": "2016-10-03T15:16:29.643Z"
    },
    "relationships": {
      "createdBy": {
        "data": {
          "id": "7fb24232-c4dc-4a90-aef8-ba5d48ca406e",
          "type": "users"
        }
      },
      "groups": {
        "data": []
      },
      "updatedBy": {
        "data": {
          "id": "7fb24232-c4dc-4a90-aef8-ba5d48ca406e",
          "type": "users"
        }
      }
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "status": 400,
  "errorMessage": "Fault"
}
Headers
Content-Type: application/json
Body
{
  "status": 401,
  "errorMessage": "Not allowed: Authentication failed.",
  "developerMessage": "auth_violation"
}
Headers
Content-Type: application/json
Body
{
  "status": 403,
  "errorMessage": "Not allowed: Forbidden, no permission to access.",
  "developerMessage": "auth_violation"
}
Headers
Content-Type: application/json
Body
{
  "status": 404,
  "errorMessage": "Not found.",
  "developerMessage": "Not found."
}
Headers
Content-Type: application/json
Body
{
  "status": 500,
  "errorMessage": "An error message"
}

Update a client
PUT/clients

Update a client.

Requires permission IDENTITY:FUNCTIONAL:CLIENT:EDIT

Clients

GET /clients
Responses200400401403404500
Headers
Content-Type: application/vnd.api+json
Body
{
  "data": [
    {
      "type": "clients",
      "attributes": {
        "confidential": true,
        "created": "2016-10-03T15:16:29.643Z",
        "label": "My Robot User",
        "redirect_url": "",
        "updated": "2016-10-03T15:16:29.643Z"
      },
      "id": "eea4e628-47e3-4ace-a973-0827de7b3ac5",
      "relationships": {
        "createdBy": {
          "data": {
            "id": "7fb24232-c4dc-4a90-aef8-ba5d48ca406e",
            "type": "users"
          }
        },
        "groups": {
          "data": []
        },
        "updatedBy": {
          "data": {
            "id": "7fb24232-c4dc-4a90-aef8-ba5d48ca406e",
            "type": "users"
          }
        }
      }
    },
    {
      "type": "clients",
      "attributes": {
        "confidential": true,
        "created": "2016-10-03T15:13:58.177Z",
        "label": "My Robot User",
        "redirect_url": "",
        "updated": "2016-10-03T15:13:58.177Z"
      },
      "id": "259730a6-2588-49c2-84f1-52c59d4b1c5a",
      "relationships": {
        "createdBy": {
          "data": {
            "id": "7fb24232-c4dc-4a90-aef8-ba5d48ca406e",
            "type": "users"
          }
        },
        "groups": {
          "data": []
        },
        "updatedBy": {
          "data": {
            "id": "7fb24232-c4dc-4a90-aef8-ba5d48ca406e",
            "type": "users"
          }
        }
      }
    },
    {
      "type": "clients",
      "attributes": {
        "confidential": true,
        "created": "2016-10-03T15:21:33.147Z",
        "label": "My Robot User",
        "redirect_url": "",
        "updated": "2016-10-03T15:21:33.147Z"
      },
      "id": "d0aa0278-2577-47d2-aab6-6f0afbf940dd",
      "relationships": {
        "createdBy": {
          "data": {
            "id": "7fb24232-c4dc-4a90-aef8-ba5d48ca406e",
            "type": "users"
          }
        },
        "groups": {
          "data": []
        },
        "updatedBy": {
          "data": {
            "id": "7fb24232-c4dc-4a90-aef8-ba5d48ca406e",
            "type": "users"
          }
        }
      }
    },
    {
      "type": "clients",
      "attributes": {
        "confidential": true,
        "created": "2016-10-03T15:12:22.643Z",
        "label": "My Robot User",
        "redirect_url": "",
        "updated": "2016-10-03T15:12:22.643Z"
      },
      "id": "06687ee0-3e9c-44de-9cd0-8a34ff564cf1",
      "relationships": {
        "createdBy": {
          "data": {
            "id": "7fb24232-c4dc-4a90-aef8-ba5d48ca406e",
            "type": "users"
          }
        },
        "groups": {
          "data": []
        },
        "updatedBy": {
          "data": {
            "id": "7fb24232-c4dc-4a90-aef8-ba5d48ca406e",
            "type": "users"
          }
        }
      }
    },
    {
      "type": "clients",
      "attributes": {
        "confidential": true,
        "created": "2016-10-03T15:25:11.357Z",
        "label": "My Robot User updated",
        "redirect_url": "http://foo.bar",
        "updated": "2016-10-04T12:06:02.447Z"
      },
      "id": "c3207730-4976-47f1-b033-8baa3d4702ff",
      "relationships": {
        "createdBy": {
          "data": {
            "id": "7fb24232-c4dc-4a90-aef8-ba5d48ca406e",
            "type": "users"
          }
        },
        "groups": {
          "data": [
            {
              "id": "1F80A5C3-3EDF-4232-83B2-FFFA062F344D",
              "type": "groups"
            }
          ]
        },
        "updatedBy": {
          "data": {
            "id": "7fb24232-c4dc-4a90-aef8-ba5d48ca406e",
            "type": "users"
          }
        }
      }
    },
    {
      "type": "clients",
      "attributes": {
        "confidential": true,
        "created": "2016-10-03T15:23:56.190Z",
        "label": "My Robot User",
        "redirect_url": "",
        "updated": "2016-10-03T15:23:56.190Z"
      },
      "id": "d43e9530-a4c2-4488-8858-ccb5890997c0",
      "relationships": {
        "createdBy": {
          "data": {
            "id": "7fb24232-c4dc-4a90-aef8-ba5d48ca406e",
            "type": "users"
          }
        },
        "groups": {
          "data": []
        },
        "updatedBy": {
          "data": {
            "id": "7fb24232-c4dc-4a90-aef8-ba5d48ca406e",
            "type": "users"
          }
        }
      }
    },
    {
      "type": "clients",
      "attributes": {
        "confidential": true,
        "created": "2016-10-03T15:02:34.877Z",
        "label": "My Robot User",
        "redirect_url": "",
        "updated": "2016-10-03T15:02:34.877Z"
      },
      "id": "e7a40665-624c-4d2b-9a9d-ced98d01fe7a",
      "relationships": {
        "createdBy": {
          "data": {
            "id": "7fb24232-c4dc-4a90-aef8-ba5d48ca406e",
            "type": "users"
          }
        },
        "groups": {
          "data": []
        },
        "updatedBy": {
          "data": {
            "id": "7fb24232-c4dc-4a90-aef8-ba5d48ca406e",
            "type": "users"
          }
        }
      }
    }
  ],
  "links": {
    "first": "/clients?page%5Blimit%5D=20&page%5Boffset%5D=0",
    "last": "/clients?page%5Blimit%5D=20&page%5Boffset%5D=0",
    "next": "/clients?page%5Blimit%5D=20&page%5Boffset%5D=0",
    "prev": "/clients?page%5Blimit%5D=20&page%5Boffset%5D=0",
    "self": "/clients?page%5Blimit%5D=20&page%5Boffset%5D=0"
  },
  "meta": {
    "count": 7,
    "found": 7
  }
}
Headers
Content-Type: application/json
Body
{
  "status": 400,
  "errorMessage": "Fault"
}
Headers
Content-Type: application/json
Body
{
  "status": 401,
  "errorMessage": "Not allowed: Authentication failed.",
  "developerMessage": "auth_violation"
}
Headers
Content-Type: application/json
Body
{
  "status": 403,
  "errorMessage": "Not allowed: Forbidden, no permission to access.",
  "developerMessage": "auth_violation"
}
Headers
Content-Type: application/json
Body
{
  "status": 404,
  "errorMessage": "Not found.",
  "developerMessage": "Not found."
}
Headers
Content-Type: application/json
Body
{
  "status": 500,
  "errorMessage": "An error message"
}

List clients
GET/clients

List all clients belonging to your company

Requires permission IDENTITY:FUNCTIONAL:CLIENTS:READ

URI Parameters
HideShow
page[offset]
integer (optional) Example: 0

(default: 0, min: 0)

page[limit]
integer (optional) Example: 20

(default: 20, min: 0, max: 200)

GET /clients/uuid
Responses200400401403404500
Headers
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "clients",
    "id": "fbd71de5-5674-42f6-a66a-4e05e7c861ed",
    "attributes": {
      "label": "My client",
      "confidential": true,
      "redirect_url": "",
      "created": "2016-10-03T15:16:29.643Z",
      "updated": "2016-10-03T15:16:29.643Z"
    },
    "relationships": {
      "createdBy": {
        "data": {
          "id": "7fb24232-c4dc-4a90-aef8-ba5d48ca406e",
          "type": "users"
        }
      },
      "groups": {
        "data": []
      },
      "updatedBy": {
        "data": {
          "id": "7fb24232-c4dc-4a90-aef8-ba5d48ca406e",
          "type": "users"
        }
      }
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "status": 400,
  "errorMessage": "Fault"
}
Headers
Content-Type: application/json
Body
{
  "status": 401,
  "errorMessage": "Not allowed: Authentication failed.",
  "developerMessage": "auth_violation"
}
Headers
Content-Type: application/json
Body
{
  "status": 403,
  "errorMessage": "Not allowed: Forbidden, no permission to access.",
  "developerMessage": "auth_violation"
}
Headers
Content-Type: application/json
Body
{
  "status": 404,
  "errorMessage": "Not found.",
  "developerMessage": "Not found."
}
Headers
Content-Type: application/json
Body
{
  "status": 500,
  "errorMessage": "An error message"
}

Get a Security Group
GET/clients/{id}

Get a security group by id.

Requires permission IDENTITY:FUNCTIONAL:CLIENTS:READ

URI Parameters
HideShow
id
string (required) Example: uuid

client id

DELETE /clients/uuid
Responses204400401403404500
Headers
Content-Type: application/vnd.api+json
Headers
Content-Type: application/json
Body
{
  "status": 400,
  "errorMessage": "Fault"
}
Headers
Content-Type: application/json
Body
{
  "status": 401,
  "errorMessage": "Not allowed: Authentication failed.",
  "developerMessage": "auth_violation"
}
Headers
Content-Type: application/json
Body
{
  "status": 403,
  "errorMessage": "Not allowed: Forbidden, no permission to access.",
  "developerMessage": "auth_violation"
}
Headers
Content-Type: application/json
Body
{
  "status": 404,
  "errorMessage": "Not found.",
  "developerMessage": "Not found."
}
Headers
Content-Type: application/json
Body
{
  "status": 500,
  "errorMessage": "An error message"
}

Delete a client
DELETE/clients/{id}

Delete a client by id.

Requires permission IDENTITY:FUNCTIONAL:CLIENT:DELETE

URI Parameters
HideShow
id
string (required) Example: uuid

client id

Generated on 17 Nov 2016