User Accounts

Managing users and accounts

In this section:


Create an Account

POST /accounts

Create a new user account.

Authorization

This endpoint must be called by the partner admin user.

Request Body

Warning: External IDs must be completely anonymized and must never contain any personally identifiable information (PII).

Parameter Type Optional Description
external_user_id string No The external ID of the account. Must be unique across all accounts created by the calling partner.

Sample Request Body

{
  "external_user_id": "abc321"
}

Response Body

Parameter Type Optional Description
id uuid No The ID of the account.
external_user_id string No The external ID of the account.

Sample Response Body

{
  "id": "eff3b9cf-df82-477a-ac12-c0e01b90bf6e",
  "external_user_id": "abc123",
}

Get a Specific Account

GET /accounts/{account_id}

Retrieves the account with the specified account ID.

Authorization

This endpoint must be called by the partner admin user, or by the user that the specified account belongs to.

Path Parameters

Parameter Type Optional Description
account_id uuid No The ID of the account to retrieve.

Response Body

Parameter Type Optional Description
id uuid No The ID of the account.
external_user_id string No The external ID of the account.
entitlements string[] Yes Entitlements that have been granted to this account. Absent if account has no entitlements. Otherwise, one or more of: “all”, “knerd”, “partner_admin”, “partner_inventory_access”, “partner_graph_update”, “partner_graph_ingest”, “partner_graph_validate”, “create_learning_instance”.

Sample Response

{
  "id": "eff3b9cf-df82-477a-ac12-c0e01b90bf6e",
  "external_user_id": "abc123",
  "entitlements": ["create_learning_instance"],
}

Get the Account of the Caller

GET /accounts/current

Retrieves the account of the calling user (the user whose oauth token or credentials are used to authorize the request). Note: this call is typically only used to ensure OAuth is setup correctly.

Authorization

This endpoint may be called by any valid user.

Response Body

See GET /accounts/{account_id} Response Body

Disable an Account

DELETE /accounts/{account_id}

Disables the specified account and marks it as inactive. Note that this operation does not make the account’s external user ID available for re-use.

Authorization

This endpoint must be called by the partner admin user.

Path Parameters

Parameter Type Optional Description
account_id uuid No The ID of the account to delete.

Creating Many Accounts (DEPRECATED)

POST /batch

Create up to 50 accounts in a single batch request.

Authorization

This endpoint must be called by the partner admin user.

Request Body

Parameter Type Optional Description
requests object[] No A list of requests to be processed by the batch call
requests[].method string No Must be “post”
requests[].relative_url string No Must be “/accounts”
requests[].body object No Body of the embedded API request. See POST /accounts Request Body.

Sample Request Body

{
  "requests": [
    {
      "method": "post",
      "relative_url": "/accounts",
      "body": {
        "external_user_id": "abc321"
      }
    },
    {
      "method": "post",
      "relative_url": "/accounts",
      "body": {
        "external_user_id": "abc322"
      }
    },
    {
      "method": "post",
      "relative_url": "/accounts",
      "body": {
        "external_user_id": "abc322"
      }
    }
  ]
}

Response Body

Parameter Type Optional Description
responses object[] No A list of responses to the individual requests in the batch.
responses[].code integer No The HTTP response code indicating the outcome of the individual account creation operation.
responses[].body object No Body of the response of the individual account creation operation. See POST /accounts Response Body.

Sample Response Body

{
  "responses" : [
    {
      "code": 200,
      "body": {
        "external_user_id": "abc321",
        "account_id": "828815a2-5038-4352-a681-82c96921ddf5",
      }
    },
    {
      "code": 200,
      "body": {
        "external_user_id": "abc322",
        "account_id": "edd9d421-3979-4249-82f8-955684d715ea",
      }
    },
    {
      "code": 422,
      "body": {
        "code": 422,
        "error_message": "Duplicate account with abc322"
      },
    }
  ]
}