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:

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": 3,
    "id": "acme-simulations",
    "projects": {
        "private": 4,
        "authenticated": 3,
        "public": 0,
        "total": 7
    },
    "accountingCode": "5d46786f-fa0a-4fe7-cffc-c2dbce1e8bc0",
    "hosting": {
        "billingInterval": "yearly",
        "allowNodeJs": true,
        "authenticatedProjectLimit": 10,
        "name": "epicenter-2014-large-yearly",
        "maxUsers": 1000
    },
    "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.

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{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!