forio Toggle navigation

Account API

The Account API provides create, read, update, and delete (CRUD) capabilities for accounts on the Epicenter platform.

An account represents a preson or organization with control over projects: Each account can have 0 or more projects.

Every Epicenter author can create personal projects. In this case, the account identifier is the User ID in the Epicenter user interface.

Epicenter authors who belong to a team collaborate to develop projects. Any team member can create a new team project. In this case, the account identifier is the Team ID in the Epicenter user interface.

In general, working with the Account API is done only by Epicenter administrators (using the user access token from an administrator login). However, Epicenter authors who are team members can also use the Account API to update teams of which they are members.

The Account API supports the following HTTP methods:

POST: Creating an Account

Use the Account API POST method to create a new account.


Method: POST

URI: /v2/account

Headers: Content-Type: application/json, Authorization: Bearer{user access token}

Body: JSON object with account record details (see Notes, below, for field details).

Return Status:

  • 201: Successfully created account.

Return Body: A JSON object with the account record just created.


Example:

curl -X POST 'https://api.forio.com/v2/account' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \
    --data '{"name": "ACME Simulations, Inc.", "id": "acme-simulations",  "type": "team"}'

Example Response:

{
    "projectsUsed": 0,
    "id": "acme-simulations",
    "projects": {
        "private": 0,
        "authenticated": 0,
        "public": 0,
        "total": 0
    },
    "accountingCode": "5d46786f-fa0a-4fe7-cffc-c2dbce1e8bc0",
    "created": "2015-02-10T18:31:06.000Z",
    "type": "team",
    "projectsLimit": 0,
    "lastModified": "2015-02-10T18:31:06.000Z",
    "url": "acme-simulations",
    "userId": "f0508d39-c50e-41be-be29-3f0aed53322f",
    "name": "ACME Simulations, Inc."
}

Notes:

  • In the request body, the following fields are required:

    • id: The unique identifier for this account. (In the Epicenter user interface, this is called Team ID or User ID.) Can contain lowercase letters, numbers, hyphens, and underscores only.
    • name: The descriptive name of this account. (In the Epicenter user interface, this is called Team Name, or for personal accounts, is the same as the id.)
    • userId: The id of the user creating this account. Required ONLY if type is individual.
  • In the request body, the following fields are optional:

    • type: Whether one Epicenter author (individual) or multiple authors (team) can contribute to projects under this account.
    • hosting: An object describing the kind of subscription for this account. Only the name is editable; the other fields in the object are populated automatically based on the name. The Epicenter user interface displays some of this information, read-only, to authors of the accounts. (Only Epicenter system administrators can make changes to this object.) The fields in this object include:
      • name: the name of the subscription plan. Required if type is team; automatically defaults to epicenter-2014-personal-monthly if type is individual.
      • allowNodeJs: whether Node.js is enabled for this account; true or false. Read only and populated based on name.
      • personal: whether the type of subscription plan is for a personal account (true) or a team account (false). (Under current conventions, true means that the third part of the name must be personal.) Read only and populated based on name.
      • maxUsers: the maximum number of end users allowed for this account. (Under currently defined subscription plans, this is only valid if personal is false.) Read only and populated based on name.
      • authenticatedProjectLimit: the maximum number of projects with an access level of authenticated. (Under currently defined subscription plans, this is only non-zero if personal is false.) Read only and populated based on name.
      • billingInterval: whether the subscription is billed or invoiced monthly or yearly. (Under current conventions, this matches the fourth part of the name.)
    • projects: An object describing the number of projects currently under this account. The fields in this object include:
      • private: The number of projects with access of private.
      • authenticated: The number of projects with access of authenticated. (Under currently defined subscription plans, the account must have a type of team in order to have authenticated projects.)
      • public: The number of projects with access of public.
      • total: The sum of private, public, and authenticated. Read only; automatically updated by the API when any of the other projects fields are updated.
  • A successful request to create an account automatically creates a new group:

    • If the account has a type of team, then the newly created group has a type of account, and will be the collection of Epicenter authors (team members) that belong to this team.
    • If the account has a type of individual, then the newly created group is an individual type group.

      Learn more about the Group API and the types of groups.

GET: Viewing Details about Accounts

You can retrieve details about any account using the Account API GET method.

Retrieving Details about One Account


Method: GET

URI: /v2/account/{account id}

Headers: Authorization: Bearer{user access token}

Return Status: 200 (successful response)

Return Body: The record (JSON object) for the account.


Example:

curl -G \
    'https://api.forio.com/v2/account/acme-simulations/' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9'

Example Response:

{
    "projectsUsed": 0,
    "id": "acme-simulations",
    "projects": {
        "private": 0,
        "authenticated": 0,
        "public": 0,
        "total": 0
    },
    "accountingCode": "5d46786f-fa0a-4fe7-cffc-c2dbce1e8bc0",
    "hosting": {
        "billingInterval": "monthly",
        "allowNodeJs": false,
        "authenticatedProjectLimit": 0,
        "name": "epicenter-2014-personal-monthly",
        "maxUsers": 0
    },
    "created": "2015-02-10T18:31:06.000Z",
    "userId": "f0508d39-c50e-41be-be29-3f0aed53322",
    "url": "acme-simulations",
    "lastModified": "2015-02-10T18:48:00.000Z",
    "type": "team",
    "projectsLimit": 0,
    "name": "ACME Simulations, Inc."
}

Notes:

  • In the URI, the Account ID is the Team ID (for team projects) or User ID (for personal projects).

Retrieving Details about Multiple Accounts


Method: GET

URI: /v2/account/?{ampersand-separated query parameters}

Headers: Authorization: Bearer{user access token}

Return Status: 200 (successful response)

Return Body: An array of account records (JSON objects).


Example:

curl -G \
    'https://api.forio.com/v2/account/?q=acme' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9'

Example Response:

[
    {
        "projectsUsed": 0,
        "id": "acme-simulations",
        "projects": {
            "private": 3,
            "authenticated": 5,
            "public": 2,
            "total": 10
        },
        "accountingCode": "1a5c0d46-2d4f-4bfc-cb48-4b92b9dea4a1",
        "hosting": {
            "billingInterval": "yearly",
            "allowNodeJs": true,
            "authenticatedProjectLimit": 25,
            "name": "epicenter-2014-large-yearly",
            "maxUsers": 5000
        },
        "created": "2014-09-12T18:00:18.000Z",
        "type": "team",
        "projectsLimit": 0,
        "lastModified": "2014-09-12T18:00:18.000Z",
        "userId": "f0508d39-c50e-41be-be29-3f0aed53322f",
        "name": "acme-simulations",
        "url": "acme-simulations"
    },
    // other accounts matching query, if any
]

Notes:

  • In the URI, you can query for EXACT match by adding id= or type=and the string to match. This returns records where the filtered field is exactly equal to the supplied string.
    • The valid values for type are team and individual.
    • For example: https://api.forio.com/v2/account/?id=acme-simulations.
  • In the URI, you can query for PARTIAL match by adding the query parameter, q, and the substring. This returns records where the substring is a full or partial match to either id or name. Include the query parameter multiple times to return records that include all of the terms (search is "AND").
    • For example: https://api.forio.com/v2/account/?q=acme.
  • In the URI, you can SORT the results in the array returned by including the query parameters sort and direction (ASC or DESC).
    • For example: https://api.forio.com/v2/account/?q=acme&sort=name&direction=ASC.
  • In the header, the Access Token can be either the user access token for a user or team member, or the project access token for this project.

Paging: Retrieving Many Records at Once

When you use the GET method for an API, your request may return many records at once.

The default page size is 100 (for most APIs) or 1000 (for the Data API). You can limit the number of records returned by adding the Range header.


Method: GET

URI: Any Epicenter API call

Headers: Range: records {i}-{j}

Return Status:

  • 200: Successfully retrieved all records
  • 206: Successfully retrieved the partially complete response, for example if you request records 0-20 and there are 35 records
  • 416: No records are found in a given search range (e.g. Range: records 10-15 when there are only 8 records)

Response Headers:

Whether or not you add the Range header to your request, the response header contains:

Content-Range: records i-j/k

where

  • i is the index of the first record returned
  • j is the index of the last record returned
  • k is the total number of records in the result set, or * if that number is computationally infeasible (for example, because you are querying across multiple projects)

For example, Content-Range: records 0-9/57 or Content-Range: records 20-29/*.

Response Body: An array of records. The array includes only those records indicated in the Content-Range header.


Example:

curl -G \
    'https://api.forio.com/v2/EpicenterAPI' \
    --header 'Range: records i-j'

Notes:

  • If no records are returned, the response body is empty.

  • If you leave off the start index, this is considered an implied start index of 0 rather than an invalid range. The response header includes status code of 200 or 206 depending on the ending index.

  • This use of the Range header is part of the RFC 2616 (see details in Section 14.16 and 14.35).

PATCH: Partially Updating an Account

You can update an existing account record (that is, replace one or more fields) using the Account API PATCH method.


Method: PATCH

URI: /v2/account/{account id}

Headers: Content-Type: application/json, Authorization: Bearer{access token}

Body: JSON object with name-value pairs of the fields to update and the values with which to update them. Fields available to change include: name.

Return Status:

  • 200: Successfully updated account

Return Body: A JSON object with the account record just updated.


Example:

curl -X PATCH 'https://api.forio.com/v2/account/acme-simulations' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \
    --data '{"name": "ACME Simulations, LLC"}'

Example Response:

{
    "projectsUsed": 0,
    "id": "acme-simulations",
    "projects": {
        "private": 0,
        "authenticated": 0,
        "public": 0,
        "total": 0
    },
    "accountingCode": "5d46786f-fa0a-4fe7-cffc-c2dbce1e8bc0",
    "created": "2015-02-10T18:31:06.000Z",
    "type": "team",
    "projectsLimit": 0,
    "lastModified": "2015-02-10T18:31:06.000Z",
    "url": "acme-simulations",
    "userId": "f0508d39-c50e-41be-be29-3f0aed53322f",
    "name": "ACME Simulations, LLC."
}

Notes:

  • The account's id, url, userId, and created fields cannot be changed.
  • The account's lastModified field cannot be changed directly but changes automatically when any of the other fields are updated.
  • Epicenter administrators can also change the following fields:
    • type: Whether one user (individual) or multiple users (team) can contribute to projects under this account.
    • hosting: An object describing the kind of subscription for this account. The Epicenter user interface displays some of this information, read-only, to users of the accounts. (Only Epicenter system administrators, who are members of the global group, can make changes to this object.) The fields in this object include:
      • name: the name of the subscription plan, e.g. epicenter-2014-large-monthly.
      • allowNodeJs: whether Node.js is enabled for this account; true or false.
      • personal: whether the type of subscription plan is for a personal account (true) or a team account (false).
      • maxUsers: the maximum number of end users allowed for this account. (Under currently defined subscription plans, this is only valid if personal is false.)
      • authenticatedProjectLimit: the maximum number of projects with an access level of authenticated. (Under currently defined subscription plans, this is only non-zero if personal is false.)
      • billingInterval: whether the subscription is billed or invoiced monthly or yearly. (Under current conventions, this matches the third part of the name.)
    • projects: An object describing the number of projects currently under this account. The fields in this object include:
      • private: The number of projects with access of private.
      • authenticated: The number of projects with access of authenticated. (Under currently defined subscription plans, the account must have a type of team in order to have authenticated projects.)
      • public: The number of projects with access of public.

DELETE: Removing an Account

You can remove an account using the Account API DELETE method.


Method: DELETE

URI: /v2/account/{account id}

Headers:

  • Content-Type: application/json,
  • Authorization: Bearer{user access token}

Body: none

Return Status:

  • 200: Account successfully removed

Return Body:

  • The account record just deleted.

Example:

curl -X DELETE 'https://api.forio.com/v2/account/acme-simulations' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \

Example Response:

{
    "projectsUsed": 0,
    "id": "acme-simulations",
    "projects": {
        "private": 3,
        "authenticated": 5,
        "public": 2,
        "total": 10
    },
    "accountingCode": "1a5c0d46-2d4f-4bfc-cb48-4b92b9dea4a1",
    "hosting": {
        "billingInterval": "yearly",
        "allowNodeJs": true,
        "authenticatedProjectLimit": 25,
        "name": "epicenter-2014-large-yearly",
        "maxUsers": 5000
    },
    "created": "2014-09-12T18:00:18.000Z",
    "type": "team",
    "projectsLimit": 0,
    "lastModified": "2014-09-12T18:00:18.000Z",
    "userId": "f0508d39-c50e-41be-be29-3f0aed53322f",
    "name": "ACME Simulations, Inc.",
    "url": "acme-simulations"
}

Notes:

  • Important: This request also deletes all of the projects created under this account. Additionally, it deletes the associated groups and memberships. Use with care!