forio Toggle navigation

Member API

The Member API allows you to look up information about end users for your project and how they are divided into groups.

Typically this is only needed for Authenticated projects, that is, projects with end users and groups. For example, if some of your end users are facilitators, or if your end users should be treated differently based on which group they are in, use the Member API to find that information.

The Member API supports the following HTTP methods:

Background: Types of Groups

Groups are collections of users. In Epicenter, there are five different types of groups. When working with the Member API, the type of group is usually included in the URI (endpoint), for example, /v2/member/local/myGroupId.

IMPORTANT: As an Epicenter author, you will probably only ever work directly with members of local groups when working on your project. The local group is a collection of end users.

For completeness, the other types of groups are:

  • account type groups are collections of users (team members) that belong to this team.
  • project type groups are collections of users (team members) that can collaborate on this project.
  • local type groups are collections of end users that can play with your project (model or simulation), for example, the students in a class or the participants at an event.
  • personal type groups are special, singleton collections of users: Each individual user of Epicenter belongs to a group whose type is personal and whose only member is that user.
  • There is one global type group, to which Epicenter system administrators belong.

POST: Adding a Member to a Group

Use the Member API POST method to add end users to a local group, that is, to make an end user a member of the group.

Method: POST

URI: /v2/member/local/{group id}

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

Body:

  • JSON object with the userId, and optionally other information (role, runLimit, expirationDate).
  • Array of such objects, if adding multiple end users to the group at once.

Return Status:

  • 201: User successfully added to group
  • 401: Invalid access rights (e.g. not a valid project access token, or using the user access token of someone not a team member)
  • 403: The group already contains group.maxUsers members

Return Body: JSON object with membership information about the user just added, or an array of such objects.

Example (adding one user):

curl -X POST 'https://api.forio.com/v2/member/local/0000015984e07e3c637540c3aaf060e3822c' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \
    --data '{"userId": "0000015984e07e3c637540c3aaf060e38158"}'

Example Response (adding one user):

{
  "added": "2017-01-13T00:00:40.018Z",
  "expirationDate": "2017-01-13T00:00:40.210Z",
  "memberType": "USER",
  "role": "standard",
  "groupId": "0000015984e07e3c637540c3aaf060e3822c",
  "userId": "0000015984e07e3c637540c3aaf060e38158",
  "userName": "user3",
  "firstName": "test",
  "lastName": "User",
  "active": true,
  "id": 26
}

Example (adding many users):

curl -X POST 'https://api.forio.com/v2/member/local/0000015984e07e3c637540c3aaf060e3822c' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \
    --data '[{"userId": "0000015984e07e3c637540c3aaf060e38242"}, {"userId": "0000015984e07e3c637540c3aaf060e3824c", "role": "facilitator"}]'

Example Response (adding many users):

[
  {
    "added": "2017-01-13T00:05:01.932Z",
    "expirationDate": "2017-01-13T00:05:01.983Z",
    "memberType": "USER",
    "role": "standard",
    "groupId": "0000015984e07e3c637540c3aaf060e3822c",
    "userId": "0000015984e07e3c637540c3aaf060e38242",
    "userName": "user6",
    "firstName": "test",
    "lastName": "User",
    "active": true,
    "id": 27
  },
  {
    "added": "2017-01-13T00:05:01.992Z",
    "expirationDate": "2017-01-13T00:05:02.066Z",
    "memberType": "USER",
    "role": "facilitator",
    "groupId": "0000015984e07e3c637540c3aaf060e3822c",
    "userId": "0000015984e07e3c637540c3aaf060e3824c",
    "userName": "fac2",
    "firstName": "fac",
    "lastName": "User",
    "active": true,
    "id": 28
  }
]

Notes:

  • In the URI, you can find the appropriate group id from the URL within the Epicenter authoring platform:
    • From your project home page (Dashboard > [Team Name] > [Project Name]), select Groups from the left.
    • Select a group name to see a list of end users in the group.
    • Check the URL for this page. It has the pattern: https://forio.com/epicenter/{team id}/{project id}/groups/{group id}.
  • In the header, the access token can be the access token from the project, from a team member, or from a end user in this group with a role of facilitator.
  • It is possible to add users to other types of groups (replacing local with the group type in the URI). However, such requests require platform administrator access, for example the user access token of an Epicenter administrator, or a token created with the manager's public and private API keys (client id and secret).
  • In the body, the userId is the (system-wide) unique identifer for this user. You can find it for example by querying the User API.
  • In the body, the optional arguments include:
    • role: The options include: standard (the default value), facilitator. Users can only have one role in a group.
    • runLimit: The number of runs for this end user.
    • expirationDate: When the end user's access to the project expires.
    • active: Boolean, whether this end user is currently a participating member of the group. A common use case is if the group represents a class: end users who do not attend on a particular day can be marked with an active of false. The multiplayer worlds only automatically assign end users with an active of true.
  • The end users being added to this team's group must be already belong to this team.
  • If the group was created with a value for runLimitDefault or expirationDate, these values are inherited by the new member record (with expirationDate truncated to the day).

GET: Viewing Details about End Users and Groups in your Project

You can retrieve details about end users of your team with the Member API GET method.

Retrieving Details about One End User in your Team

Method: GET

URI: /v2/member/local/?userId={user id}

Headers: Authorization: Bearer{access token}

Return Status:

  • 200: Successfully retrieved record
  • 401: Invalid access rights (for example, the end user is not a member of your team)

Return Body: An array of records (JSON objects), one for each group in which the end user belongs. Each group record includes the project (Project ID) and account (Team ID), plus the name and groupId for the group and an array of members. However, only the user whose userId is included in the URI is listed in the members array (regardless of whether there are other members in this group).

Example:

curl -G \
    'https://api.forio.com/v2/member/local?userId=0000015984e07e3c637540c3aaf060e38242' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9'

Example Response:

[
      {
        "type": "local",
        "created": "2017-01-09T23:24:55.000Z",
        "lastModified": "2017-01-13T00:05:02.000Z",
        "startDate": "2017-01-09T00:00:00.000Z",
        "expirationDate": "2017-01-31T00:00:00.000Z",
        "id": "0000015984e07e3c637540c3aaf060e3822c",
        "groupId": "0000015984e07e3c637540c3aaf060e3822c",
        "name": "mgmt-300-seminar",
        "account": "acme-simulations",
        "project": "supply-chain-game",
        "userCount": 3,
        "maxUsers": 40,
        "members": [
          {
            "added": "2017-01-13T00:05:02.000Z",
            "expirationDate": "2017-01-13T00:20:23.358Z",
            "memberType": "USER",
            "role": "standard",
            "groupId": "0000015984e07e3c637540c3aaf060e3822c",
            "userId": "0000015984e07e3c637540c3aaf060e38242",
            "userName": "user6",
            "firstName": "test",
            "lastName": "User",
            "active": true,
            "id": 27
          }
        ]
      },
    ... // other projects of which this end user is a member, if any
]

Notes:

  • In the header, the access token can be the access token from the project, from a team member, or from a end user in this group with a role of facilitator.
  • In the response body, the details inside the members array describe how this end user relates to this group. (Some of the information is a copy of what is already in the end user record.)
  • Members in groups that have expired (e.g. the date is past the group expiration date) are not shown by default. This allows a simulation to get a list of all active groups. To include all memberships, whether or not they are expired, include the query parameter includeExpired=true.

Using POST to Retrieve Many Records at Once

Sometimes when you would like to use the GET method for an API, your request may require a very long URI, for example: https://api.forio.com/v2/user?id=0b31ee58-6cef-488c-9825-19469376b70c&id=0f97e39b-4d45-475e-b710-8a6459db24cf&id=....

For these situations, Epicenter APIs support the option of using a POST method with additional parameters in place of the GET method.

Method: POST

URI:

  • Any Epicenter API call that supports GET with query parameters
  • Followed by ?_method=GET

Headers:

  • Authorization header as required by the Epicenter API in question (e.g. Authorization: Bearer{project access token})
  • Content-Type: application/json

Body: JSON object describing the query. For example:

  • {"id": ["0b31ee58-6cef-488c-9825-19469376b70c", "0f97e39b-4d45-475e-b710-8a6459db24cf"]}

Return Status:

  • 200: Successfully retrieved records

Return Body: Array of records (JSON objects) returned by the query.

Example:

curl -X POST 'https://api.forio.com/v2/user?_method=GET' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \
        --data '{"id": ["0b31ee58-6cef-488c-9825-19469376b70c", "0f97e39b-4d45-475e-b710-8a6459db24cf"]}'

Notes:

  • While using POST and query parameter ?_method=GET to retrieve many records at once is available in all Epicenter APIs, it is generally most useful in the User, Member, and Model Run APIs because of the frequency of doing longer queries with those APIs.

Retrieving Details about All End Users in a Group

Method: GET

URI: /v2/member/local/{group id}

Headers: Authorization: Bearer{access token}

Return Status: 200 (successful response)

Return Body: A record (JSON object) for the group, including the project (Project ID) and account (Team ID), and an array of members. For each member, the role, userId, runLimit (if applicable), and expirationDate are included.

Example:

curl -G \
    'https://api.forio.com/v2/member/local/0000015984e07e3c637540c3aaf060e3822c' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9'

Example Response:

{
  "type": "local",
  "created": "2017-01-09T23:24:55.000Z",
  "lastModified": "2017-01-13T00:05:02.000Z",
  "startDate": "2017-01-09T00:00:00.000Z",
  "expirationDate": "2017-01-31T00:00:00.000Z",
  "id": "0000015984e07e3c637540c3aaf060e3822c",
  "groupId": "0000015984e07e3c637540c3aaf060e3822c",
  "name": "mgmt-300-seminar",
  "account": "acme-simulations",
  "project": "supply-chain-game",
  "userCount": 3,
  "maxUsers": 40,
  "members": [
    {
      "added": "2017-01-13T00:05:02.000Z",
      "expirationDate": "2017-01-13T00:39:55.255Z",
      "memberType": "USER",
      "role": "standard",
      "groupId": "0000015984e07e3c637540c3aaf060e3822c",
      "userId": "0000015984e07e3c637540c3aaf060e38242",
      "userName": "user6",
      "firstName": "test",
      "lastName": "User",
      "active": true,
      "id": 27
    },
    // ... other end users in this group, if any
  ]
}

Notes:

  • In the header, the access token can be the access token from the project, from a team member, or from a end user in this group with a role of facilitator.
  • You can find the appropriate group id from the URL within the Epicenter authoring platform:
    • From your project home page (Dashboard > [Team Name] > [Project Name]), select Groups from the left.
    • Select a group name to see a list of end users in the group.
    • Check the URL for this page. It has the pattern: https://forio.com/epicenter/{team id}/{project id}/groups/{group id}.
  • In the response body, the details inside the members array describe how each end user relates to this group. (Some of the information is a copy of what is already in the end user record.)

PUT: Replacing Details about Members and Groups

Use the Member API PUT method to replace details about how an end user relates to a group.

Method: PUT

URI: /v2/member/local/{group id}/{user id}

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

Body:

  • JSON object with the information to update (role, runLimit, expirationDate).

Return Status:

  • 200: User successfully added to group
  • 401: Invalid access rights (e.g. not a valid project access token, or using the user access token of someone not a team member)

Return Body: The JSON object of the updated member record.

Example:

curl -X PUT 'https://api.forio.com/v2/member/local/0000015984e07e3c637540c3aaf060e3822c/0000015984e07e3c637540c3aaf060e38242' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \
    --data '{ "role": "standard", "runLimit": 15 }'

Example Response:

{
  "added": "2017-01-13T00:05:02.000Z",
  "expirationDate": "2017-01-13T00:42:17.645Z",
  "memberType": "USER",
  "role": "standard",
  "groupId": "0000015984e07e3c637540c3aaf060e3822c",
  "userId": "0000015984e07e3c637540c3aaf060e38242",
  "userName": "user7",
  "firstName": "test",
  "lastName": "User",
  "active": true,
  "id": 28,
  "runLimit": 15
}

Notes:

  • Note that the entire member record is replaced! This means that usually the request body should contain all fields, not just the one you are updating. (For example, do a query for this member record before making this request.)
    • In particular, make sure to pass in the role for facilitators, or it will be replaced with the default role of standard.
    • Alternatively, consider using the PATCH request instead.
  • In the URI, you can find the appropriate group id from the URL within the Epicenter authoring platform:
    • From your project home page (Dashboard > [Team Name] > [Project Name]), select Groups from the left.
    • Select a group name to see a list of end users in the group.
    • Check the URL for this page. It has the pattern: https://forio.com/epicenter/{team id}/{project id}/groups/{group id}.
  • In the URI, the userId is the (system-wide) unique identifer for this user. You can find it for example by querying the User API.
  • In the header, the access token can be the access token from the project, from a team member, or from a end user in this group with a role of facilitator.
  • In the body, the optional arguments include:
    • role: The options include: standard (the default value), facilitator, customer_support. Users can only have one role in a group.
    • runLimit: The number of runs for this end user.
    • expirationDate: When the end user's access to the project expires.
    • active: Boolean, whether this end user is currently a participating member of the group. A common use case is if the group represents a class: end users who do not attend on a particular day can be marked with an active of false. The multiplayer worlds only automatically assign end users with an active of true.
  • You cannot update a member record to change the user id. Use DELETE and then POST to create a new membership for the different user.

PATCH: Updating Details about Members and Groups

Use the Member API PATCH method to update specific details about how an end user relates to a group.

Method: PATCH

URI:

  • /v2/member/local/{group id}/{user id} to update membership details for one user
  • /v2/member/local/{group id}?userId={user id}&userId={user id} to update membership details for multiple users

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

Body:

  • JSON object with the information to update (e.g. role, runLimit, expirationDate)

Return Status:

  • 200: Membership details successfully updated
  • 401: Invalid access rights (e.g. not a valid project access token, or using the user access token of someone not a team member)

Return Body:

  • When updating one user (user id in URI): The JSON object of the updated member record.
  • When updating multiple users (user ids as query parameters): An array of the update member records.

Example:

curl -X PATCH 'https://api.forio.com/v2/member/local/0000015984e07e3c637540c3aaf060e3822c/0000015984e07e3c637540c3aaf060e3824c' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \
    --data '{"runLimit": 5}'

Example Response:

{
  "added": "2017-01-13T00:05:02.000Z",
  "expirationDate": "2017-01-13T00:43:26.833Z",
  "memberType": "USER",
  "role": "facilitator",
  "groupId": "0000015984e07e3c637540c3aaf060e3822c",
  "userId": "0000015984e07e3c637540c3aaf060e3824c",
  "userName": "fac2",
  "firstName": "fac",
  "lastName": "User",
  "active": true,
  "id": 28,
  "runLimit": 5
}

Notes:

  • In the URI, you can find the appropriate group id from the URL within the Epicenter authoring platform:
    • From your project home page (Dashboard > [Team Name] > [Project Name]), select Groups from the left.
    • Select a group name to see a list of end users in the group.
    • Check the URL for this page. It has the pattern: https://forio.com/epicenter/{team id}/{project id}/groups/{group id}.
  • In the URI, the userId is the (system-wide) unique identifer for this user. You can find it for example by querying the User API.
  • In the header, the access token can be the access token from the project, from a team member, or from a end user in this group with a role of facilitator.
  • In the body, the optional arguments include:
    • role: The options include: standard (the default value), facilitator, customer_support. Users can only have one role in a group.
    • runLimit: The number of runs for this end user.
    • expirationDate: When the end user's access to the project expires.
    • active: Boolean, whether this end user is currently a participating member of the group. A common use case is if the group represents a class: end users who do not attend on a particular day can be marked with an active of false. The multiplayer worlds only automatically assign end users with an active of true.
  • You cannot update a member record to change the user id. Use DELETE and then POST to create a new membership for the different user.

DELETE: Removing a Member from a Group

Use the Member API DELETE method to remove end users from a group.

Method: DELETE

URI:

  • /v2/member/local/{group id}/{user id} for removing one membership
  • /v2/member/local/{group id}?userId={user id}&userId={user id} for removing multiple memberships

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

Body: none

Return Status:

  • 200: User successfully removed from group
  • 401: Invalid access rights (e.g. not a valid project access token, or using the user access token of someone not a team member)

Return Body:

  • When removing one membership (user id in URI): The JSON object of the member record just deleted.
  • When removing multiple memberships (user ids as query parameters): An array of the member records just deleted.

Example:

curl -X DELETE 'https://api.forio.com/v2/member/local/0000015984e07e3c637540c3aaf060e3822c/0000015994c18670b35cdf4c97de708d8184' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \

Example Response:

{
  "added": "2017-01-13T00:48:50.000Z",
  "expirationDate": "2017-01-13T00:49:17.080Z",
  "memberType": "USER",
  "role": "standard",
  "groupId": "0000015984e07e3c637540c3aaf060e3822c",
  "userId": "0000015994c18670b35cdf4c97de708d8184",
  "userName": "user22",
  "firstName": "test",
  "lastName": "User",
  "active": true,
  "id": 30
}

Notes:

  • In the URI, you can find the appropriate group id from the URL within the Epicenter authoring platform:
    • From your project home page (Dashboard > [Team Name] > [Project Name]), select Groups from the left.
    • Select a group name to see a list of end users in the group.
    • Check the URL for this page. It has the pattern: https://forio.com/epicenter/{team id}/{project id}/groups/{group id}.
  • In the URI, the userId is the (system-wide) unique identifer for this user. You can find it for example by querying the User API.
  • In the header, the access token can be the access token from the project, from a team member, or from a end user in this group with a role of facilitator.
  • Deleting an account also automatically deletes any memberships under that account.
  • When you remove an end user from a group, the end user is automatically removed from all worlds in that group. See additional information in the Multiplayer World API.