Users

APIs for creating and manipulating users

Users are a main component of the BitBroker system. You will find more details about users, within the key concepts section of this documentation.

Every fresh installation of BitBroker comes with one preinstalled user (uid: 1). This user is automatically created when the system is bought-up for the first time.

In our sample calls, we use the standard server name and port format outlined for local installations and demos. If you have an alternative API host base URL, then enter it in the box below to update all the sample calls on this page :

Your API Host Base URL

All API calls in BitBroker require authorization. The sample calls below contain a placeholder string where you should insert your coordinator API authorization token. If you already have a token, enter it in the box below to update all the sample calls on this page:

Your Coordinator API Authorization Token

Creating a New User

New users can be created by issuing an HTTP/POST to the /user end-point.

curl http://bbk-coordinator:8001/v1/user \
     --request POST \
     --include \
     --header "Content-Type: application/json" \
     --header "x-bbk-auth-token: your-token-goes-here" \
     --data-binary @- << EOF
     { \
         "name": "Alice", \
         "email": "alice@domain.com" \
     }
EOF

This will result in a response as follows:

HTTP/1.1 201 Created
Location: http://bbk-coordinator:8001/v1/user/2

The ID for the new user will be returned within the Location attribute of the response header.

The following validation rules will be applied to the body of a new user request.

Attribute	Necessity	Validation Rules
`name`	required	String between 1 and 64 characters long
`email`	required	String between 1 and 256 characters long Must conform to email address format Must be unique across all users in the system

Email addresses need to be unique across an operating BitBroker instance. If you attempt to create a user with a duplicate email address, it will result in an HTTP/1.1 409 Conflict response.

New users will be present in the system right away. They can immediately take part as data consumers by being assigned policy-based, consumer authorization tokens. However, a further step is required to promote them to have coordinator status.

Updating a User

Existing users can have their profile updated by issuing an HTTP/PUT to the /user/:uid end-point.

In order to update a user, you must know their user ID (uid).

curl http://bbk-coordinator:8001/v1/user/2 \
     --request PUT \
     --include \
     --header "Content-Type: application/json" \
     --header "x-bbk-auth-token: your-token-goes-here" \
     --data-binary @- << EOF
     { \
         "name": "Bob" \
     }
EOF

This will result in a response as follows:

HTTP/1.1 204 No Content

You cannot update the user’s email address, which was specified when they were created. Email addresses are system-wide unique identifiers. If you need to update an email address, your only option is to create a new user with that address.

The validation rules for updated user information, are the same as that for creating new users.

List of Existing Users

You can obtain a list of all the existing users by issuing an HTTP/GET to the /user end-point.

curl http://bbk-coordinator:8001/v1/user \
     --header "x-bbk-auth-token: your-token-goes-here"

This will return a JSON array as follows:

[
    {
        "id": 1,
        "url": "http://bbk-coordinator:8001/v1/user/1",
        "name": "Admin",
        "email": "noreply@bit-broker.io",
        "coordinator": true,
        "accesses": []
    },
    {
        "id": 2,
        "url": "http://bbk-coordinator:8001/v1/user/2",
        "name": "Bob",
        "email": "alice@domain.com",
        "coordinator": false,
        "accesses": []
    }
    // ... other users here
]

Each user on the system will be returned within this array. Later sections of this document will explain what the coordinator and accesses attributes refer to. Note: There is currently no paging on this API.

Details of an Existing User

You can obtain the details of an existing user by issuing an HTTP/GET to the /user/:uid end-point.

In order to obtain details of a user, you must know their user ID (uid).

curl http://bbk-coordinator:8001/v1/user/2 \
     --header "x-bbk-auth-token: your-token-goes-here"

This will return a JSON object as follows:

{
    "id": 2,
    "url": "http://bbk-coordinator:8001/v1/user/2",
    "name": "Bob",
    "email": "alice@domain.com",
    "coordinator": false,
    "accesses": [],
    "addendum": {}
}

Later sections of this document will explain what the coordinator, accesses and addendum attributes refer to.

Finding a User via Email Address

You can find an existing user via their email address by issuing an HTTP/GET to the /user/email/:email end-point.

In order to obtain details of a user, you must know their current email address.

curl http://bbk-coordinator:8001/v1/user/email/alice%40domain.com \
     --header "x-bbk-auth-token: your-token-goes-here"

For best practice, the email address within this RESTful URL should be url encoded.

This will return a JSON object as follows:

{
    "id": 2,
    "url": "http://bbk-coordinator:8001/v1/user/2",
    "name": "Bob",
    "email": "alice@domain.com",
    "coordinator": false,
    "accesses": [],
    "addendum": {}
}

Promoting a User to Coordinator

Existing users can be promoted to assign them coordinator status by issuing an HTTP/POST to the /user/:uid/coordinator end-point.

In order to promote a user, you must know their user ID (uid).

curl http://bbk-coordinator:8001/v1/user/2/coordinator \
     --request POST \
     --include \
     --header "x-bbk-auth-token: your-token-goes-here"

This will result in a response as follows:

HTTP/1.1 200 OK

The body of this response will contain the coordinator authorization token, which the newly promoted user should utilize to authorize their own calls to the Coordinator API. For example:

4735d360-dc03-499c-91ce-68dfc1554691.5d5c9eab-1d9c-4c88-9478-9f4ab35568a7.423c9101-315a-4929-a64c-9b905837799c

It is expected that the promoting user will securely distribute this coordinator authorization token to the promoted user.

Promoted users will gain coordinator privileges right away. When getting details for such users, their coordinator status will be reflected in the coordinator attribute:

{
    "id": 2,
    "url": "http://bbk-coordinator:8001/v1/user/2",
    "name": "Bob",
    "email": "alice@domain.com",
    "coordinator": true,  // this is the new coordinator status
    "accesses": [],
    "addendum": {}
}

If you attempt to promote a user who is already a coordinator, it will result in an HTTP/1.1 409 Conflict response. This error is benign and will not impact the user’s status.

Demoting a User from Coordinator

Existing users can be demoted from coordinator status by issuing an HTTP/DELETE to the /user/:uid/coordinator end-point.

In order to demote a user, you must know their user ID (uid).

curl http://bbk-coordinator:8001/v1/user/2/coordinator \
     --request DELETE \
     --include \
     --header "x-bbk-auth-token: your-token-goes-here"

This will result in a response as follows:

HTTP/1.1 204 No Content

Demoted users will lose coordinator privileges right away. The coordinator authorization token they were holding will no longer be valid. When getting details for such users, their coordinator status will be reflected in the coordinator attribute:

{
    "id": 2,
    "url": "http://bbk-coordinator:8001/v1/user/2",
    "name": "Bob",
    "email": "alice@domain.com",
    "coordinator": false,  // this is the new coordinator status
    "accesses": [],
    "addendum": {}
}

If you attempt to demote a user who is not a coordinator, it will result in an HTTP/1.1 409 Conflict response. This error is benign and will not impact the user’s status.

Demoting a user has no impact on any policy authorization tokens which they may be holding for the Consumer API.

You cannot demote yourself from being a coordinator. If you attempt this, the system will return an HTTP/1.1 405 Method Not Allowed response. This is done in order to prevent a situation where there are no coordinators present within an operating instance. If you wish to demote yourself, you will need to ask another coordinator to perform this action on your behalf.

Deleting a User

Existing users can be deleted from the system by issuing an HTTP/DELETE to the /user/:uid end-point.

In order to delete a user, you must know their user ID (uid).

curl http://bbk-coordinator:8001/v1/user/2 \
     --request DELETE \
     --include \
     --header "x-bbk-auth-token: your-token-goes-here"

This will result in a response as follows:

HTTP/1.1 204 No Content

Any policy authorization tokens which were assigned to a deleted user will be rescinded as part of the deletion process. Consumer API requests made with such tokens will fail (after a short propagation delay).

You cannot delete yourself from the system. If you attempt this, the system will return an HTTP/1.1 405 Method Not Allowed response. This is done in order to prevent a situation where there are no users present within an operating instance. If you wish to delete yourself, you will need to ask another coordinator to perform this action on your behalf.

User Addendum Information

Observant readers will have noticed an addendum section at the bottom of the user details object:

{
    "id": 2,
    "url": "http://bbk-coordinator:8001/v1/user/2",
    "name": "Bob",
    "email": "alice@domain.com",
    "coordinator": false,  
    "accesses": [],
    "addendum": {}  // this is the addendum section
}

This section is reserved for use by the up-coming BitBroker Portal. We request that you do not use this section at this time.