Account Management

Nexla provides the following resources for managing accounts:

  1. Users: User resources describe individual Nexla accounts. Every user has a corresponding User resource and may belong to an org through Org memberships. Each user can belong to none or more than one organization, but there is no cross availability of user's resources across the organizations.

  2. Organizations: Umbrella resource for grouping multiple users together. Resource access controls are walled by organization boundary.

  3. Teams: A team resource defines a collections of users, either within an organization or as individuals with no associated organization.

Users

User resources describe individual Nexla accounts. Every user has a corresponding User resource and may belong to an org through Org memberships.

Fetch Current User

Users can fetch their information by calling the GET /users endpoint. This response contains only one entry - their own information.

Fetch Current User: Request
GET /users
Fetch Current User: Response
[
{
"id": 2,
"email": "demo_1@demonexla.com",
"full_name": "Demo User1",
"api_key": "<API-Key>",
"super_user": true,
"impersonated": false,
"default_org": {
"id": 2,
"name": "Nexla Demo"
},
"org_memberships": [
{
"id": 2,
"name": "Nexla Demo",
"is_admin?": true,
"api_key": "<Org-API-Key>"
}
],
"email_verified_at": "2017-05-31T15:47:15.000Z",
"updated_at": "2017-08-30T21:48:10.000Z",
"created_at": "2017-05-31T15:47:15.000Z"
}
]

List All Users

Organization admins can list all users that belong to their org by including the access_role=all query param to /users endpoint.

List All Users: Request
GET /users?access_role=all
List All Users: Response
[
{
"id": 1,
"email": "demo_admin@demonexla.com",
"full_name": "Demo Admin",
"api_key": "<API-Key>",
"super_user": true,
"impersonated": false,
"default_org": {
"id": 2,
"name": "Nexla Demo"
},
"org_memberships": [
{
"id": 2,
"name": "Nexla Demo",
"is_admin?": true,
"api_key": "<Org-API-Key>"
}
],
"email_verified_at": "2017-05-31T15:47:15.000Z",
"updated_at": "2017-05-31T15:47:15.000Z",
"created_at": "2017-05-31T15:47:15.000Z"
},
{
"id": 2,
"email": "demo_1@demonexla.com",
"full_name": "Demo User1",
"api_key": "<API-Key>",
"super_user": true,
"impersonated": false,
"default_org": {
"id": 2,
"name": "Nexla Demo"
},
"org_memberships": [
{
"id": 2,
"name": "Nexla Demo",
"is_admin?": true,
"api_key": "<Org-API-Key>"
}
],
"email_verified_at": "2017-05-31T15:47:15.000Z",
"updated_at": "2017-08-30T21:48:10.000Z",
"created_at": "2017-05-31T15:47:15.000Z"
}
]

Add User to Organization

Organization admins can add a user to their organization and optionally make them org administrators. The payload should contain email, full_name and admin selection for creating a new user.

Add User to Organization: Request
PUT /orgs/{org_id}
...
Example Request Payload:
{
"users":[
{
"email":"demo123@nexlademo.com",
"full_name":"Demo User123",
"admin": false
}
]
}

Teams

A team resource defines a collections of users, either within an Org or as individuals with no associated Org.

Note: All members of a team belonging to an Org must be also be members of that Org.

Teams are useful for managing access rights to other Nexla resources. Access rights to data sources and sets, for example, can be granted to a team, which grants the team's access rights to each member of the team.

Users added to an existing team are automatically granted any resource access rights already granted to the team. Those rights are removed when a team member is removed from the team, unless the member has access through another grant.

Any user can create a team, either within an Org they belong to or as an individual user. The user who creates a team is the team's owner, but is not automatically a member of the team (this allows Org admins to create teams to which they do not belong). All team members must be explicitly added using one of the POST or PUT requests described in this section.

List Teams You Own

Make a GET request to the /teams endpoint to list all of the teams owned by the authenticated user. A successful request returns with status 200 and a JSON response containing an array of team objects.

List Teams You Own: Request
GET /teams
List Teams You Own: Response
[
{
"id": 5,
"owner": {
"id": 2,
"full_name": "Jeffrey Williams",
"email": "jcw@nexla.com"
},
"org": {
"id": 1,
"name": "Nexla",
"email_domain": "nexla.com",
"email": null
},
"member": false,
"access_roles": ["owner"],
"name": "Testing Team",
"description": null,
"members": [
{
"id": 4,
"email": "saket@nexla.com",
"admin": true
}
],
"updated_at": "2019-04-21T17:12:06.000Z",
"created_at": "2019-04-21T17:12:06.000Z"
},
{
"id": 7,
"owner": {
"id": 2,
"full_name": "Jeffrey Williams",
"email": "jcw@nexla.com"
},
"org": {
"id": 1,
"name": "Nexla",
"email_domain": "nexla.com",
"email": null
},
"member": true,
"access_roles": ["member", "owner"],
"name": "Example Team",
"description": "A team with two members",
"members": [
{
"id": 2,
"email": "jcw@nexla.com",
"admin": true
},
{
"id": 3,
"email": "niket@nexla.com",
"admin": true
}
],
"updated_at": "2019-04-21T19:20:01.000Z",
"created_at": "2019-04-21T19:20:01.000Z"
}
]

List Teams You Belong To

Set the access_role query parameter to member when making a GET request to the /teams endpoint to list only the teams the requester is a member of.

List Teams You Belong To: Request
GET /teams?access_role=member
List Teams You Belong To: Response
[
{
"id": 7,
"owner": {
"id": 2,
"full_name": "Jeffrey Williams",
"email": "jcw@nexla.com"
},
"org": {
"id": 1,
"name": "Nexla",
"email_domain": "nexla.com",
"email": null
},
"member": true,
"access_roles": ["member", "owner"],
"name": "Example Team",
"description": "A team with two members",
"members": [
{
"id": 2,
"email": "jcw@nexla.com",
"admin": true
},
{
"id": 3,
"email": "niket@nexla.com",
"admin": true
}
],
"updated_at": "2019-04-21T19:20:01.000Z",
"created_at": "2019-04-21T19:20:01.000Z"
}
]

Show One Team

Make a GET request to the /teams endpoint with a specific team id to retrieve only that resource. A successful /teams/<team_id> request returns with status 200 and a JSON response containing a team object.

Show One Team: Request
GET /teams/{team_id}
Show One Team: Response
{
"id": 5,
"owner": {
"id": 2,
"full_name": "Jeffrey Williams",
"email": "jcw@nexla.com"
},
"org": {
"id": 1,
"name": "Nexla",
"email_domain": "nexla.com",
"email": null
},
"member": false,
"access_roles": ["owner"],
"name": "TEST test",
"description": null,
"members": [
{
"id": 4,
"email": "saket@nexla.com",
"admin": true
}
],
"updated_at": "2019-04-21T17:12:06.000Z",
"created_at": "2019-04-21T17:12:06.000Z"
}

Create A Team

Issue a POST request to the /teams endpoint to create a new team. A team name is required; all other attributes, including members, are optional.

Include the members array attribute to add users to the new Team during creation. Each array element must be an object with either an email or id attribute specifying the user. The object may also optionally contain an admin boolean attribute that specifies whether the user should be able to administer the Team. If admin is not present, it is assumed to be false:

[
{
"email": "jcw@nexla.com",
"admin": true
},
{
"id": 3
}
]
Create A Team: Request
POST /teams
...
Example Request Payload
{
"name": "Example Team",
"description": "A team with two members",
"members": [
{
"email": "jcw@nexla.com",
"admin": true
},
{
"email": "niket@nexla.com"
}
]
}
Create A Team: Response
{
"id": 7,
"owner": {
"id": 2,
"full_name": "Jeffrey Williams",
"email": "jcw@nexla.com"
},
"org": {
"id": 1,
"name": "Nexla",
"email_domain": "nexla.com",
"email": null
},
"member": true,
"access_roles": ["member", "owner"],
"name": "Example Team",
"description": "A team with two members",
"members": [
{
"id": 2,
"email": "jcw@nexla.com",
"admin": true
},
{
"id": 3,
"email": "niket@nexla.com",
"admin": false
}
],
"updated_at": "2019-04-21T19:20:01.546Z",
"created_at": "2019-04-21T19:20:01.546Z"
}

Update A Team

Issue a PUT request to the /teams/<team_id> endpoint to update an existing team.

Note Team members may only be added or have their team admin rights updated using this endpoint. To replace a team's member list or to delete members from it, use the /teams/<team_id>/members endpoint described below.

Update A Team: Request
PUT /teams/{team_id}
...
Example Request Body
{
"name": "Example Team Updated",
"members": [
{
"email": "niket@nexla.com",
"admin": true
}
]
}
Update A Team: Response
{
"id": 7,
"owner": {
"id": 2,
"full_name": "Jeffrey Williams",
"email": "jcw@nexla.com"
},
"org": {
"id": 1,
"name": "Nexla",
"email_domain": "nexla.com",
"email": null
},
"member": true,
"access_roles": ["member", "owner"],
"name": "Example Team Updated",
"description": "A team with two members",
"members": [
{
"id": 2,
"email": "jcw@nexla.com",
"admin": true
},
{
"id": 3,
"email": "niket@nexla.com",
"admin": true
}
],
"updated_at": "2019-04-21T19:38:44.925Z",
"created_at": "2019-04-21T19:20:01.000Z"
}

List Team Members

Make a GET request to the /teams/<team_id>/members endpoint to list only the members of the specified team. A successful/teams/<team_id>/members request returns with status 200 and a JSON response containing an array of team member objects.

List Team Members: Request
GET /teams/{team_id}/members
List Team Members: Response
[
{
"id": 2,
"email": "jcw@nexla.com",
"admin": true
},
{
"id": 3,
"email": "niket@nexla.com",
"admin": true
}
]

Update Team Members

Make a PUT request to the /teams/<team_id>/members endpoing to add members or to change the admin status of existing users. This endpoint behaves exactly as PUT /teams/<team_id> does when that endpoint receives a request body including a members attribute.

Note You cannot remove members or replace the entire member list using this endpoint. See the following sections.

Update Team Members: Request
PUT /teams/{team_id}/members
...
Example Request Payload
{
"members": [
{
"email": "niket@nexla.com",
"admin": false
}
]
}
Update Team Members: Response
[
{
"id": 2,
"email": "jcw@nexla.com",
"admin": true
},
{
"id": 3,
"email": "niket@nexla.com",
"admin": false
}
]

Replace Team Members

Make a POST request to the /teams/<team_id>/members endpoint to replace the existing list of members with a new one. You can remove all members by passing an empty list to this endpoint. A successful POST request to /teams/<team_id>/members returns with status 200 and a JSON response containing an array of team member objects.

Replace Team Members: Request
POST /teams/{team_id}/members
...
Example Request Payload
{
"members": [
{
"email": "saket@nexla.com",
"admin": true
}
]
}
Replace Team Members: Response
[
{
"id": 4,
"email": "saket@nexla.com",
"admin": true
}
]

Delete Team Members

Make a DELETE request to the /teams/<team_id>/members endpoint to remove members from a team.

Delete Team Members: Request
DELETE /teams/{team_id}/members
...
Example Request Payload
{
"members": [
{
"email": "saket@nexla.com"
}
]
}
Delete Team Members: Response
[]

Delete Team

Issue a DELETE request to the /teams/<team_id> endpoint to delete a team. The requester must be the owner or an admin of the team.

If the team being deleted is currently granted any access permissions to any resources, DELETE will fail with a response status of 405, Method Not Allowed, unless force=1 is passed as a query parameter.

Otherwise, a successful DELETE request returns a status 200, Ok, and an empty response body.

Delete Team Members: Request
DELETE /teams/{team_id}
Delete Team Members: Response
{
"message": "Include force=1 as a query parameter to delete team with active access permissions"
}