API Details¶

The Seed Identity Store provides REST like API with JSON payloads.

The root URL for all of the endpoints is:

https://<identity-store-domain>/api/

Authenticating to the API¶

Please see the Authentication and Authorization document.

Pagination¶

When the results set is larger than a configured amount, the data is broken up into pages using the limit and offset parameters.

Paginated endpoints will provide information about the total amount of items available along with links to the previous and next pages (where available) in the returned JSON data.

GET /(any)/

Query Parameters:
	limit – the amount of record to limit a page of results to. offset – the starting position of the query in relation to the complete set of unpaginated items
Response JSON Object:
	count (int) – the total number of results available previous (string) – the URL to the previous page of results (if available) next (string) – the URL to the next page of results (if available)

Example request:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "count": 50,
    "next": "http://sis.example.org/api/v1/enpoint/?limit=10&offset=30",
    "previous": "http://sis.example.org/api/v1/endpoint/?limit=10&offset=10",
    "results": []
}

Endpoints¶

The endpoints provided by the Seed Identity Store are split into two categories, core endpoints and helper endpoints

Core¶

The root URL for all of the core endpoints includes the version prefix (https://<identity-store-domain>/api/v1/)

Users and Groups¶

GET /user/¶

Returns a list of users for the Seed Identity Store service.

Status Codes:	200 OK – no error. 401 Unauthorized – the token is invalid/missing.

Example request:

GET /user/ HTTP/1.1
Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "email": "john@example.org",
            "groups": [],
            "url": "http://sis.example.org/api/v1/user/1/",
            "username": "john"
        }
    ]
}

GET /user/(int: user_id)/¶

Returns the details of the specified user ID.

Parameters:	user_id (int) – a user’s unique ID.
Status Codes:	200 OK – no error. 401 Unauthorized – the token is invalid/missing.

Example request:

GET /user/1/ HTTP/1.1
Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "email": "john@example.org",
    "groups": [],
    "url": "http://sis.example.org/api/v1/user/1/",
    "username": "john"
}

POST /user/token/¶

Creates a user and token for the given email address.

If a user already exists for the given email address, the existing user account is used to generate a new token.

Request JSON Object:
	email (string) – the email address of the user to create or use.
Response JSON Object:
	token (string) – the auth token generated for the given user.
Status Codes:	201 Created – token successfully created. 400 Bad Request – an email address was not provided or was invalid. 401 Unauthorized – the token is invalid/missing.

Example request:

POST /user/token/ HTTP/1.1
Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

{
    "email": "bob@example.org"
}

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
    "token": "c05fbab6d5f912429052830c77eeb022249324cb"
}

GET /group/¶

Returns a list of groups for the Seed Identity Store service.

Status Codes:	200 OK – no error 401 Unauthorized – the token is invalid/missing.

Example request:

GET /group/ HTTP/1.1
Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "name": "Admins",
            "url": "http://sis.example.org/api/v1/group/1/"
        }
    ]
}

GET /group/(int: group_id)/¶

Returns the details of the specified group ID.

Parameters:	group_id (int) – a group’s unique ID.
Status Codes:	200 OK – no error. 401 Unauthorized – the token is invalid/missing.

Example request:

GET /group/1/ HTTP/1.1
Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "name": "Admins",
    "url": "http://sis.example.org/api/v1/group/1/"
}

Identities¶

GET /identities/¶

Returns a list of identities.

Status Codes:	200 OK – no error. 401 Unauthorized – the token is invalid/missing.

Example request:

GET /identities/ HTTP/1.1
Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
    ]
}

POST /identities/¶

Create a new identity.

Request JSON Object:
	version (int) – optional version number of the Identity schema being used. details (json) – a JSON object representing the Identity details communicate_through (string) – optional URL to another identity that represents an Identity to communicate through. operator (string) – optional optional URL to another identity that presents an operator that is responsible for this Identity
Response JSON Object:
	id (uuid) – the UUID of this Identity version (int) – the version number of the Identity schema being used. details (json) – the JSON object representing the Identity details communicate_through (url) – URL to another identity that represents an Identity to communicate through. operator (url) – URL to another identity that presents an operator that is responsible for this Identity created_at (datetime) – the date and time this Identity was created created_by (datetime) – the ID of the user that created this Identity updated_at (datetime) – the date and time this Identity was last updated updated_by (datetime) – the ID of the user that created this Identity
Status Codes:	201 Created – identity successfully created. 400 Bad Request – the details field was not provided or was invalid. 401 Unauthorized – the token is invalid/missing.

Example request:

POST /user/ HTTP/1.1
Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

{
    "details": {
        "addresses": {
        "msisdn": {
            "+27115551234": {}
        },
    },
    "version": 1
}

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
    "communicate_through": null,
    "created_at": "2016-09-30T11:10:21.693326Z",
    "created_by": 1,
    "details": {
        "addresses": {
           "msisdn": {
                "+27115551234": {}
            }
        }
    }
}
    },
    "id": "4be7c1f9-f3a1-4bb3-ade7-a193ca2e79d0",
    "operator": null,
    "updated_at": "2016-09-30T11:10:21.693364Z",
    "updated_by": 1,
    "version": 1
}

GET /identities/(uuid: identity_id)/¶

Returns the Identity record for a given UUID.

Status Codes:	200 OK – no error 401 Unauthorized – the token is invalid/missing.

PUT /identities/(uuid: identity_id)/¶

Update the Identity record for the given UUID.

Status Codes:	200 OK – no error 401 Unauthorized – the token is invalid/missing.

DELETE /identities/(uuid: identity_id)/¶

Delete the Identity record for the given UUID.

Status Codes:	204 No Content – delete successfully completed. 401 Unauthorized – the token is invalid/missing.

GET /identities/(uuid: identity_id)/addresses/(str: address_type)/¶

Searches address by a given type for a given Identity.

Status Codes:	200 OK – no error 401 Unauthorized – the token is invalid/missing.

GET /identities/search/¶

Search Identity records by specifying Django filter keys as query parameters.

Status Codes:	200 OK – no error 401 Unauthorized – the token is invalid/missing.

POST /optout/¶

Create an OptOut record.

Status Codes:	200 OK – no error 401 Unauthorized – the token is invalid/missing.

POST /optin/¶

Create an OptIn record.

Status Codes:	200 OK – no error 401 Unauthorized – the token is invalid/missing.

Other¶

GET /detailkeys/¶

Returns a list of all the unique keys stored in any detail field of an Identity record.

This list is populated by a post-save signal on the Identity record.

Status Codes:	200 OK – no error 401 Unauthorized – the token is invalid/missing.

GET /webhook/¶

Returns a list of setup webhooks.

Status Codes:	200 OK – no error 401 Unauthorized – the token is invalid/missing.

POST /webhook/¶

Creates a webhook.

Status Codes:	200 OK – no error 401 Unauthorized – the token is invalid/missing.

GET /webhook/(int: webhook_id)/¶

Get the details of a webhook specified by webhook_id.

Status Codes:	200 OK – no error 401 Unauthorized – the token is invalid/missing.

PUT /webhook/(int: webhook_id)/¶

Updates the details of a webhook specified by webhook_id.

Status Codes:	200 OK – no error 401 Unauthorized – the token is invalid/missing.

DELETE /webhook/(int: webhook_id)/¶

Deletes the webhook specified by webhook_id.

Status Codes:	200 OK – no error 401 Unauthorized – the token is invalid/missing.

Helpers¶

The root URL for the helper endpoints does not include a version prefix (https://<identity-store-domain>/api/)

GET /metrics/

Returns a list of all the available metric keys provided by this service.

Status Codes:	200 OK – no error 401 Unauthorized – the token is invalid/missing.

POST /metrics/

Starts a task that fires all scheduled metrics.

Status Codes:	200 OK – no error 401 Unauthorized – the token is invalid/missing.

GET /health/

Returns a basic health check status.

Status Codes:	200 OK – no error 401 Unauthorized – the token is invalid/missing.

API Details¶

Authenticating to the API¶

Endpoints¶

Core¶

Users and Groups¶

Identities¶

Other¶

Helpers¶

Table Of Contents

Related Topics

This Page