Skip to main content

Organizations

Introduction#

An organization is created by an end-user. Inside it, they can create boxes and administrate them. These boxes are then owned by the organization.

There is always at least one organization within the system, corresponding to what is called the "self org". The "self org" corresponds to the Open ID Provider client and represents the instance of the system running.

While end-users create boxes in their personal space, it is linked to this self-organization which represent then the personal space for all the users on this instance. Self organization has no administrators, the data linked to it belongs to the end-users that have created it.

Organizations#

Creating an Organization#

Request#

POST https://api.misakey.com/organizations

Cookies:

  • accesstoken (opaque token) (ACR >= 2): no identity check, just a valid token is required.
  • tokentype: must be bearer

Headers:

  • X-CSRF-Token: a token to prevent from CSRF attacks.

JSON Body:

{
"name": "My Org",
"secret_storage": {
"account_root_key_hash": "RIC-6ajeDex9vDM1wnLvbQ",
"asym_keys": {
"QhQp6kNDF-3HUTVS7XuXGg": {
"encrypted_secret_key": "ZGBuLodWwTbw0xb9BdxSsIQKy6dhYKX-xL2_SGFE5F4"
}
}
},
"pubkey": "QhQp6kNDF-3HUTVS7XuXGg"
}
  • name (string) (max length: 255).
  • pubkey (optional) (unpadded URL-safe base64) the organization's public key
  • secret_storage (optional) initial data for the organization's secret storage:
    • account_root_key_hash is the (SHA-512) hash of the organization's root key
    • asym_keys maps public keys to their secret key (encrypted with the root key)

Use the secret_storage field to store the secret key corresponding to the org's public key.

Response#

_

HTTP 201 Created

JSON Body:

{
"id": "91ec8274-2b6d-40ff-afad-83e8ba5808e5",
"name": "The Privacy-Esteeming Organization",
"current_identity_role": "admin",
"creator_id": "fcfacf74-b15e-4583-bb71-55eb42cf2758",
"created_at": "2020-06-12T13:38:32.142857839Z"
}

with attributes:

  • id: (string, uuid) the unique id of the organization.
  • name: (string) the name of the organization.
  • current_identity_role: (string) (nullable) (one of: admin) the role for the current identity for this organization. null is no special role attributed.
  • creator_id: (string, uuid) the id of the identity who has created the organization.
  • created_at: (date) the date of creation of the org.

Generating a Secret for an Organization#

This request is idempotent. As the secret is unknown to the server, generating a secret will always answer with a new secret either there is an existing secret for the organization.

The secret is generated by the server and returned as json body once for all. It will be never possible to retrieve it again, the server does not store it in a raw version.

Request#

PUT https://api.misakey.com/organizations/:id/secret

Cookies:

  • accesstoken (opaque token) (ACR >= 2): mid should be an admin of the organization.
  • tokentype: must be bearer

Headers:

  • X-CSRF-Token: a token to prevent from CSRF attacks.

Path parameters:

  • id: (uuid) unique id of the organization.

Response#

_

HTTP 200 Created

JSON Body:

{
"secret": "",
}

Listing organizations for the current identity#

Request#

GET https://api.misakey.com/identities/:id/organizations

Cookies:

  • accesstoken (opaque token) (ACR >= 1): mid claim as the identity id.
  • tokentype: must be bearer

Headers:

  • X-CSRF-Token: a token to prevent from CSRF attacks.

Path Parameters:

  • id (uuid string): the box id wished to be retrieved.

Response#

Code:

HTTP 200 OK

JSON Body:

[
{
"id": "91ec8274-2b6d-40ff-afad-83e8ba5808e5",
"name": "The Privacy-Esteeming Organization",
"current_identity_role": "admin",
"creator_id": "fcfacf74-b15e-4583-bb71-55eb42cf2758",
"created_at": "2020-06-12T13:38:32.142857839Z"
}
]

with attributes:

  • id: (string, uuid) the unique id of the organization.
  • name: (string) the name of the organization.
  • current_identity_role: (string) (nullable) (one of: admin) the role for the current identity for this organization. null is no special role attributed.
  • creator_id: (string, uuid) the id of the identity who has created the organization.
  • created_at: (date) the date of creation of the org.

Getting public info about an organization#

This endpoint does not need any valid token.

Request#

GET https://api.misakey.com/organizations/:id/public

Path Parameters:

  • id (uuid string): the organization id wished to be retrieved.

Response#

Code:

HTTP 200 OK

JSON Body:

{
"id": "<(uuid string): the organization id>",
"name": "<name of the organization>",
"logoUrl": "<logo of the organization>",
}

Adding an agent#

An agent wiil be able to create boxes in the organization.

An agent is different from the creator of the organization.

The creator is the only one who can create, remove and list agents.

Request#

POST https://api.misakey.com/organizations/:id/agents

Cookies:

  • accesstoken (opaque token) (ACR >= 2): identity must be creator of the organization
  • tokentype: must be bearer

Headers:

  • X-CSRF-Token: a token to prevent from CSRF attacks.

JSON Body:

{
"email": "agent@org.com",
}
  • email (string): email of the new agent

Response#

_

HTTP 201 Created

JSON Body:

{
"id": 3,
"organization_id": "fcfacf74-b15e-4583-bb71-55eb42cf2758",
"identity_id": "becaff74-b15e-4583-bb71-55eb42cf7ebf",
"created_at": "2020-06-12T13:38:32.142857839Z"
"identity": {
"id": "becaff74-b15e-4583-bb71-55eb42cf7ebf",
"display_name": "Jean Dupont",
"avatar_url": null
"identifier_value": "jean.dupont@example.com",,
"identifier_kind": "email",
}
}

with attributes:

  • id: (int) the unique id of the agent role.
  • organization_id: (string, uuid) the id of the organization.
  • identity_id: (string, uuid) the identity id of the agent.
  • created_at: (date) the date of creation of the agent.

Listing org agents#

Request#

GET https://api.misakey.com/organizations/:id/agents?limit=&offset=

Cookies:

  • accesstoken (opaque token) (ACR >= 2): identity must be creator of the organization
  • tokentype: must be bearer

Headers:

  • X-CSRF-Token: a token to prevent from CSRF attacks.

Query Parameters:

  • limit: (int, optional) the pagination limit
  • offset: (int, optional) the pagination offset

Response#

_

HTTP 200 OK

JSON Body:

[
{
"id": 3,
"organization_id": "fcfacf74-b15e-4583-bb71-55eb42cf2758",
"identity_id": "becaff74-b15e-4583-bb71-55eb42cf7ebf",
"created_at": "2020-06-12T13:38:32.142857839Z"
"identity": {
"id": "becaff74-b15e-4583-bb71-55eb42cf7ebf",
"display_name": "Jean Dupont",
"avatar_url": null
"identifier_value": "jean.dupont@example.com",,
"identifier_kind": "email",
}
}
]

with attributes:

  • id: (int) the unique id of the agent role.
  • organization_id: (string, uuid) the id of the organization.
  • identity_id: (string, uuid) the identity id of the agent.
  • created_at: (date) the date of creation of the agent.
  • identity: (json) some more information about the agent identity.

Counting org agents#

Request#

HEAD https://api.misakey.com/organizations/:id/agents

Cookies:

  • accesstoken (opaque token) (ACR >= 2): identity must be creator of the organization
  • tokentype: must be bearer

Response#

HTTP 204 No Content

Headers:

  • X-Total-Count (integer): the total count of agents in the organization.