Accounts API

Ainua Portal Accounts API provides RESTful access for Accounts integration. It is designed for integrating Accounts from a back-office solution to Ainua Portal.

For added security Accounts API is write-only as are all Ainua Portal API’s.

Note

Accounts API uses bearer_token (obtained within authentication request using a specific connector in Ainua Portal) to bind data to specific data source. Good rule of thumb is to use different connector for each back-office integration.

Combining accounts from multiple sources

It is very common that back-office solutions integrating to Ainua Portal do not share the same account identity. This is not a problem for Ainua Portal though as it provides a mechanism to bind different account identities to same Ainua Portal account identity via Accounts common identity id (typically company’s registeration id).

client_id is taken from the bearer_token obtained within authentication request using a specific connector in Ainua Portal. This is used for storing the user external identity in Ainua Portal. Good rule of thumb is to use different connector for each back-office integration.

Note

If the account identity or portal access is removed from one of the back-office solutions the identity remains in Ainua Portal as long as there is at least one back-office solution that publishes accounts there.

Updating Accounts

Request

PATCH `https://{ainua_url}/api/integrations/v1/accounts`

Header

Content-type: application/json
Authorization: Bearer {bearer_token}

Body

{
    "{account1_external_id}":
    {
        "name": "{account1_name}",
        "id":"{account1_id}"
    },
    "{account2_external_id}":
    {
        "name": "{account2_name}",
        "id":"{account2_id}"
    },
    :
}

Request will return 200 OK on success.

To remove a account provide null as account data.

{
    "{accountX_external_id}": null,
    :
}

Example

Request

PATCH `https://example.ainuaportal.com/api/integrations/v1/accounts`

Header

Content-type:   application/json
Authorization:  Bearer eyJhbGciOiJSUzI1Ni... ...PCBGj6DEN02WOIdzXEQ

Body

{
    "account_123":
    {
        "name": "Acme Ltd.",
        "id": "123456-8"
    }
}

Response

HTTP/1.0 200 OK

Binding users to an account

As described in Items API the data brought to Ainua Portal is always either non-targeted or it is bound to an account. In order to access the data bound to a specific data also the users that are granted access to it must be bound to the account. Ainua Portal makes sure to provide data user is entitled to.

One user may be bound to many accounts. When a user with multiple account signs in to Ainua Portal client he/she is promplted to select one of the accounts.

Request

PATCH `https://{ainua_url}/api/integrations/v1/accounts/{account_id}/users`

Header

Content-type: application/json
Authorization: Bearer {bearer_token}

Body

[
    "user1_external_id", "user2_external_id", ... "userX_external_id"
]

Request will return 200 OK on success.

Example

Request

PATCH `https://example.ainuaportal.com/api/integrations/v1/accounts/123456-8/users`

Header

Content-type:   application/json
Authorization:  Bearer eyJhbGciOiJSUzI1Ni... ...PCBGj6DEN02WOIdzXEQ

Body

[
    "user_001", "user_002"
]

Response

HTTP/1.0 200 OK