POST

Create Account

Use this API to create a child account under your reseller account.

OneLogin creates the account’s owner from email, firstname, lastname, and user_password. The owner is an active user with the Super user privilege and the account’s Default role. You can also ask for an API credential pair in the new account, so you can call the OneLogin API as that account straight away.

Resource URL

https://<subdomain>.onelogin.com/api/2/accounts

Header Parameters

Authorization

required

string

Set to bearer <access_token>.

Set <access_token> to the access token you generated using the Generate Token API.

The access token must have been generated using an API credential pair created using the scope required to call this API. This API can be called using Manage All.

The API credential must belong to a reseller account.

Content-Type

required

string

Set to application/json.

Request Parameters

account

required

object

The account to create. Takes the attributes below.

account.name

required

string

The account name, usually the name of the customer, company, or organization.

account.email

required

string

The email address of the account owner. It becomes the owner's email and username, stored in lowercase.

If you don't send brand_subdomain, this address must not already belong to any OneLogin user.

account.brand_subdomain

string

The subdomain of the account's OneLogin URL. For example, acme gives the account https://acme.onelogin.com.

Use lowercase letters, numbers, and single hyphens, without a hyphen at the start or end. The subdomain must not already be in use.

If you don't send it, the account is created without a OneLogin subdomain. Always send it unless you plan to set one up another way.

account.firstname

string

The account owner's first name.

account.lastname

string

The account owner's last name.

account.user_password

string

The account owner's password. It must meet the new account's default password policy.

If you don't send it, the owner has no password. Set email_activation to true so the owner gets an email to set one.

account.plan

string

The short name of the plan to subscribe the account to. Your OneLogin account manager can tell you which plan names you can use.

If you don't send it, or OneLogin doesn't recognize it, the account gets the free plan.

account.subscription_state

string

The state of the account's subscription, for example trial, sponsored, or paying. Defaults to free.

A paying state can't be used with the free plan, and a free state can't be used with a priced plan.

account.enforce_user_limit

boolean

Set to true to enforce the subscription's user limit (see orgsize).

account.address1, account.address2, account.city, account.state, account.zip, account.phone, account.homepage, account.notes

string

Optional contact details for the account. See the account object.

country is always set to US on create. Use Update Account to change it.

orgsize

integer

The number of users the account's subscription covers. Defaults to 1, which is also the minimum. Send it at the top level of the body, not inside account.

email_activation

boolean

Set to true to email the account owner a link to set their password and activate the account. Defaults to false. Send it at the top level of the body.

api_credential

object

Creates an API credential pair in the new account, owned by the account owner. Send it at the top level of the body. It takes:

  • name (required): the credential's display name.

  • permission (required): the credential's scope. One of authentication_only, read_users, manage_users, read_all, or manage_all.

Request Body

{
    "account": {
        "name": "Acme Inc.",
        "email": "admin@example.com",
        "brand_subdomain": "acme",
        "firstname": "Jane",
        "lastname": "Doe",
        "plan": "<plan_name>",
        "subscription_state": "trial",
        "phone": "555-555-0100"
    },
    "orgsize": 25,
    "email_activation": true,
    "api_credential": {
        "name": "Provisioning",
        "permission": "manage_all"
    }
}

Sample Responses

  • 201 Created
  • 400 Bad Request
  • 401 Unauthorized
  • 422 Unprocessable Entity

Returns the new account object. If you sent api_credential, the response also includes the new credential pair. Store the client_secret securely.

If the account is created but the credential can’t be, the response is still 201 and api_credential is an empty object ({}). You can create a credential later with Update Account.

{
    "id": 123456,
    "name": "Acme Inc.",
    "address1": null,
    "address2": null,
    "city": null,
    "state": null,
    "zip": null,
    "country": "US",
    "phone": "555-555-0100",
    "homepage": null,
    "notes": null,
    "remotetoken": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "created_at": "2024-05-01T17:20:31.000Z",
    "updated_at": "2024-05-01T17:20:33.000Z",
    "api_credential": {
        "client_id": "<client_id>",
        "client_secret": "<client_secret>",
        "permission": "Manage All",
        "display_name": "Provisioning"
    }
}

The account object contains an attribute that doesn’t exist.

{
    "name": "BadRequestError",
    "message": "unknown attribute: company",
    "statusCode": 400
}

The access token is missing, invalid, or expired, or it was generated from a credential without the required scope. The Authorization header value should use this format: bearer <access_token>.

{
    "name": "UnauthorizedError",
    "message": "Unauthorized",
    "statusCode": 401
}

The request can’t be processed. The name tells you why:

  • ValidationError: the body has no account object.
  • RecordInvalid: an account attribute failed validation, for example a missing name or email, an email already used by another user, a brand_subdomain that’s taken or badly formatted, or an invalid plan and subscription state combination. The message lists the errors.
  • Invalid parameters: api_credential is missing its name or has an unknown permission. The account isn’t created.
  • Insufficient privileges: the API credential doesn’t belong to a reseller account.
{
    "status": 422,
    "name": "RecordInvalid",
    "message": "Brand subdomain has already been taken, Validation failed: Brand subdomain has already been taken"
}
{
    "status": 422,
    "name": "Invalid parameters",
    "message": "API credential name cannot be blank, API credential permission is invalid"
}

Sample Code

cURL

Replace sample values indicated by < > with your actual values.

Create Account

curl 'https://<subdomain>.onelogin.com/api/2/accounts' \
-X POST \
-H "Authorization: bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
    "account": {
        "name": "Acme Inc.",
        "email": "admin@example.com",
        "brand_subdomain": "acme",
        "firstname": "Jane",
        "lastname": "Doe",
        "plan": "<plan_name>",
        "subscription_state": "trial"
    },
    "orgsize": 25,
    "email_activation": true,
    "api_credential": {
        "name": "Provisioning",
        "permission": "manage_all"
    }
}'