Session management API Documentation

• Overview
  • Request / Response Format
  • Pagination
  • Error Handling
  • Filtering
• Authentication
  • Clients
  • Management Interface
• Users
  • Fields
  • GET /users/
  • POST /users/
  • GET /users/:id/
  • PUT /users/:id/
  • PATCH /users/:id/
  • DELETE /users/:id/
  • POST /users/:id/password_change/
  • POST /users/:id/password_set/
  • POST /users/:id/block/
  • POST /users/:id/unblock/
• Events
  • Fields
  • GET /events/
  • POST /events/
  • GET /events/:id/
  • PUT /events/:id/
  • PATCH /events/:id/
  • DELETE /events/:id/
  • GET /events/:id/archives/
• Sessions
  • Fields
  • GET /sessions/
  • POST /sessions/
  • GET /sessions/:id/
  • PUT /sessions/:id/
  • PATCH /sessions/:id/
  • DELETE /sessions/:id/
• Login Tokens
  • Fields
  • GET /logintokens/
  • POST /logintokens/
  • GET /logintokens/:id/
  • PUT /logintokens/:id/
  • PATCH /logintokens/:id/
  • DELETE /logintokens/:id/
• RTC Sessions
  • POST /rtcsessions/
• Booking Emails
  • POST /bookingemails/
• Network Test Session
  • POST /networktestsessions/

Sesssion management API

{protocol}://{host}/api/v2

Overview

Request / Response Format

All requests should be made in JSON. All calls are returned in JSON.

API users should set HTTP Accept: application/json and Content-Type:application/json headers.

Pagination

Collection results in the API are grouped in pages, to avoid huge responses if a lot of data is available.

Page size is at 100 by default. The page size can be set using the limit URL parameter and the page offset can be set using the offset parameter. Example for getting entries 100-150:

http GET /api/v2/events/?limit=50&offset=2 Authorization:"JWT <token>"

Error Handling

If the API returns an error, the error details are returned as JSON. There are different error cases.

General Errors

General errors are returned in the detail field:

{
  "detail": "Authentication credentials were not provided."
}

Form Errors

Field-specific errors are returned as an array of error messages, with the key being the field name:

{
  "password": ["This field is required."]
}

General errors are returned as an array of error messages, with the key being “non- FieldErrors”:

{
  "nonFieldErrors": [
    "Unable to login with provided credentials."
  ]
}

Filtering

To only return entries with a field matching a certain value, you can also use filters. E.g. to get all sessions belonging to a certain event, you can use the ?event=eventId GET parameter:

http GET /sessions/?event=3 Authorization:"JWT d34db33f(...)"

To get all disabled events where the subscribers may see the floor session:

http GET /events/?subscribersSeeFloor=False&disabled=True \
    Authorization:"JWT d34db33f(...)"

NOTE: Due to technical implementation details, boolean values need to be sent as True and False, not true and false.

Authentication

Clients

Each client will get a static API token. The token should be stored in the client in an obfuscated way. The token will be sent along with every request, in the Authorization header:

Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

Since a client cannot modify any data, there is no additional authentication needed besides the login token.

Management Interface

The endpoints needed for the management interface are protected by using JSON Web Tokens (JWT).

Rationale and introduction to JWT:

• https://auth0.com/blog/5-steps-to-add-modern-authentication-to-legacy-apps-using-jwts/
• https://jwt.io/introduction/

JWT Libraries should be available for all major languages and frameworks.

Obtaining a token

These tokens can be obtained by sending a username and password to the server via POST request:

http POST /token-auth/obtain/ username=test password=testpass
HTTP/1.0 200 OK
Content-Type: application/json
Date: Fri, 23 Dec 2016 10:15:10 GMT

{
  "token": "eyJ0eXAiOiJK(...)aBqroY"
}

If the credentials are invalid, the following HTTP400 response will be returned:

http POST /token-auth/obtain/ username=test password=testpass
HTTP/1.0 400 BAD REQUEST
Content-Type: application/json
Date: Fri, 23 Dec 2016 10:15:10 GMT

{
  "non_field_errors": ["Unable to login with provided credentials."]
}

Or if the user account has been blocked:

http POST /token-auth/obtain/ username=test password=testpass
HTTP/1.0 400 BAD REQUEST
Content-Type: application/json
Date: Fri, 23 Dec 2016 10:15:10 GMT

{
  "non_field_errors": ["User account is blocked."]
}

Using a token

The token needs to be in the Authorization HTTP header with every request:

http GET / Authorization:"JWT eyJ0eXAiOiJK(...)aBqroY"

HTTP/1.0 200 OK
Content-Type: application/json
Date: Fri, 23 Dec 2016 10:21:25 GMT

{
  "bookingemails": "http://localhost:8001/api/v2/bookingemails/",
  "events": "http://localhost:8001/api/v2/events/",
  "logintokens": "http://localhost:8001/api/v2/logintokens/",
  "networktestsessions": "http://localhost:8001/api/v2/networktestsessions/",
  "rtcsessions": "http://localhost:8001/api/v2/rtcsessions/",
  "sessions": "http://localhost:8001/api/v2/sessions/",
  "users": "http://localhost:8001/api/v2/users/"
}

Token claims

Note that the JWT token contains information about the logged in user. To test this, you can go to https://jwt.io#debugger-io and enter the token on the left side. On the right side, you will see the encoded payload:

{
  "username": "test",
  "user_id": 12,
  "email": "test@example.com",
  "exp": 1470054971
}

As you can see, the JWT token contains username, user id and e-mail address.

Token expiration and renewal

Note also, that the JWT token expires. The expiration date is contained in the exp field of the JWT payload as a unix timestamp. The default expiration is 7 days after being issued. There's a 1 hour tolerance after the expiration where the token will still be accepted by the server.

To get a new token, either request a new one using username or password, or use the refresh endpoint. To refresh, pass in your existing token. You'll get a new token in return:

http POST :8000/api/v2/token-auth/refresh/ token="eyJ0eXAiOiJK(...)aBqroY"
HTTP/1.0 200 OK
Content-Type: application/json
Date: Fri, 23 Dec 2016 10:24:58 GMT

{
  "token":"eyJhbGciOiJIUzI1NiIsInR(...)-EYLI"
}

The new token will be valid again for 7 days. Refreshing a token only works if the old one is still valid.

Refresh with tokens can be repeated (token1 -> token2 -> token3), but refreshing is only possible up to 30 days after the initial token was issued.

This mechanism allows a web app to keep the user logged in if the time since the last login is not longer than 7 days. It is recommended to refresh a token every day, to prevent it from expiring.

Users

Fields

• id: Integer. Primary key of the user. Read only. Unique.
• username: String. Username. Unique.
• email: String. The e-mail address of the user.
• firstName: String. The first name of the user. May be empty.
• lastName: String. The last name of the user. May be empty.
• blocked: Boolean. Whether this user is blocked. Read only.
• role: String. The role of this user. Either admin, partner or manager.
• creator: Integer. The user PK that created this user. When creating a user, defaults to the currently logged in user. May be null.

GET /users/

Return all registered users that the currently logged in user may see.

POST /users/

Create a new user.

Required Request Fields

• username: String. Username. Unique.
• role: String. The role of this user. Either admin, partner or manager.

Optional Request Fields

• email: String. The e-mail address of the user.
• firstName: String. The first name of the user. May be an empty string.
• lastName: String. The last name of the user. May be an empty string.

GET /users/:id/

Return the specified user.

PUT /users/:id/

Update the specified user.

PATCH /users/:id/

Partially update the specified user.

DELETE /users/:id/

Delete the specified user.

POST /users/:id/password_change/

Change the password for the specified user.

If successful, the API endpoint will return a HTTP 204 status code.

Request Fields

• oldPw: String. The current password.
• newPw: String. The new password.
• newPwRepeat: String. The new password, repeated.

POST /users/:id/password_set/

As an admin, you can set passwords of any partner or manager. As a partner, you can set passwords of the managers created by you. The old password does not need to be sent.

If successful, the API endpoint will return a HTTP 204 status code.

Request Fields

• newPw: String. The new password.

POST /users/:id/block/

Users can be blocked. A blocked user cannot log in anymore. He/she will be notified on login attempt that the account has been blocked.

Simply send a POST request to this endpoint in order to block the user. No fields are required.

If successful, the API endpoint will return a HTTP 204 status code.

POST /users/:id/unblock/

Users can be unblocked.

Simply send a POST request to this endpoint in order to block the user. No fields are required.

If successful, the API endpoint will return a HTTP 204 status code.

Events

Required Authentication

JWT

Fields

• id: Integer. Primary key of the event. Read only. Unique.
• name: String. Internal name of the event. Unique.
• displayName: String. Name of the event shown to end users. May be empty or null.
• logo: String. Logo URL. May be empty or null.
• owner: Integer. The owner (creator) of the event. Defaults to the logged in user.
• managers: List of Integer. The manager(s) for the event. May be an empty list.
• disabled: Boolean. Setting this to true will make publishing / subscribing impossible. Defaults to false.
• subscribersSeeFloor: Boolean. Whether subscribers may access the floor session. Defaults to false.
• locationHint: String. When set to an IP, the IP will be used as OpenTok location hint for the event. May be empty.
• allowSourceVideo: Boolean. Defaults to false.
• quality: String. Free text. Defaults to an empty string.
• mobileDisallow: Boolean. Indicates whether the mobile app should disallow access to this event. Defaults to false.
• mobileAudienceDisallow: Boolean. Indicates whether the mobile app should disallow audience access to this event. Defaults to false.
• mobileData: String. Free text. Will be passed to the mobile app. Defaults to an empty string.
• mfa: String. Indicates whether multi-factor authentication is required. Value is not validated by the API, but should be either "phone", "email", "both" or an empty string (none). Will be passed to the mobile app. Defaults to an empty string.

GET /events/

Return all events that the currently logged in user may see.

POST /events/

Create a new event.

Required Request Fields

• name: String. Internal name of the event. Unique.

Optional Request Fields

• displayName: String. Name of the event shown to end users. May be empty or null.
• logo: String. Logo URL. May be empty or null.
• managers: List of Integer. The manager(s) for the event. May be an empty list.
• disabled: Boolean. Setting this to true will make publishing / subscribing impossible. Defaults to false.
• subscribersSeeFloor: Boolean. Whether subscribers may access the floor session. Defaults to false.
• locationHint: String. When set to an IP, the IP will be used as OpenTok location hint for the event. May be empty.
• allowSourceVideo: Boolean. Defaults to false.
• quality: String. Free text. Defaults to an empty string.
• mobileDisallow: Boolean. Indicates whether the mobile app should disallow access to this event. Defaults to false.
• mobileAudienceDisallow: Boolean. Indicates whether the mobile app should disallow audience access to this event. Defaults to false.
• mobileData: String. Free text. Will be passed to the mobile app. Defaults to an empty string.
• mfa: String. Indicates whether multi-factor authentication is required. Value is not validated by the API, but should be either "phone", "email", "both" or an empty string (none). Will be passed to the mobile app. Defaults to an empty string.

GET /events/:id/

Return the specified event.

PUT /events/:id/

Update the specified event.

PATCH /events/:id/

Partially update the specified event.

DELETE /events/:id/

Delete the specified event.

GET /events/:id/archives/

Return archive entries for sessions belonging to the specified event. See session archive documentation (GET /sessions/:id/archives/) for more information.

Sessions

Required Authentication

JWT

Fields

• id: Integer. Primary key of the session. Read only. Unique.
• event: Integer. The PK of the event that this session belongs to. Read only.
• language: String. A string describing the language, or "Floor".
• languageCode: String. Optional (nullable) language code.
• isFloor: Boolean. Whether this is a floor session. Only one session per event may have this flag set to true. Defaults to false.
• sessionId: String. Tokbox session ID. Read only. Will be generated by the API backend on save. May change when updating the session mode.
• mode: String. Routing mode for the Tokbox session. Either relayed or routed. Defaults to routed.
• archive: Boolean. Whether to enable auto archival for this session. May not be true if media mode is relayed. Defaults to true.

GET /sessions/

Return all sessions that the currently logged in user may see.

POST /sessions/

Create a new session.

Required Request Fields

• event: Integer. The PK of the event that this session belongs to.
• language: String. A string describing the language, or "Floor".

Optional Request Fields

• isFloor: Boolean. Whether this is a floor session. Only one session per event may have this flag set to true. Defaults to false.
• mode: String. Routing mode for the Tokbox session. Either relayed or routed. Defaults to routed.
• archive: Boolean. Whether to enable auto archival for this session. May not be true if media mode is relayed. Defaults to true.

GET /sessions/:id/

Return the specified session.

PUT /sessions/:id/

Update the specified session.

PATCH /sessions/:id/

Partially update the specified session.

DELETE /sessions/:id/

Delete the specified session.

Login Tokens

Login tokens are entered by the user on the website or in the app in order to connect to event sessions. They are associated with an event.

Required Authentication

JWT

Fields

• id: Integer. Primary key of the login token. Read only. Unique.
• event: Integer. The PK of the event that this login token belongs to. Read only.
• token: String. The login token that will be entered by the user. Must be at least 8 characters long. Unique.
• tokenType: String. Sets the permissions for this login token. Must be one of participant, interpreter, floor, remote or moderator.

GET /logintokens/

Return all login tokens that the currently logged in user may see.

POST /logintokens/

Create a new login token.

Required Request Fields

• event: Integer. The PK of the event that this session belongs to.
• token: String. The login token that will be entered by the user. Must be at least 8 characters long. Unique.
• tokenType: String. Sets the permissions for this login token. Must be one of participant, interpreter, floor, remote or moderator.

GET /logintokens/:id/

Return the specified login token.

PUT /logintokens/:id/

Update the specified login token.

PATCH /logintokens/:id/

Partially update the specified login token.

DELETE /logintokens/:id/

Delete the specified login token.

RTC Sessions

RTC Sessions are created by the clients, who provide a login token and get back a list of sessions and OpenTok session tokens as well as general information about the associated event.

Required Authentication

Static API Token

POST /rtcsessions/

Request session information for the specified login token.

Required Request Fields

• loginToken: String. The login token.

Optional Request Fields

• additionalAccess: List of String. The "access flags" sent in this field grant additional permissions to the chosen login token. See list below.

Access Flags

• view_floor: If this access flag is set for a participant login token, then the floor session will always be returned in the response, even if subscribersSeeFloor on the event is set to false.

HTTP Response Codes

• HTTP 201 Created: Login successful, new sessions tokens have been created
• HTTP 400 Bad Request: No login token was submitted
• HTTP 403 Forbidden: The submitted login token is invalid, or the client tried to access a non-mobile event with a mobile API token
• HTTP 404 Not Found: The event is disabled
• HTTP 500 Internal Server Error

Example Response

http POST /rtcsessions/ \
    loginToken=<logintoken> \
    additionalAccess:='["view_floor"]' \
    Authorization:"Token <apitoken>"
HTTP/1.0 201 CREATED
Content-Type: application/json
Date: Sat, 24 Dec 2016 14:54:17 GMT

{
  "event": {
    "displayName": "Test Event",
    "id": 4,
    "locationHint": "1.2.3.4",
    "allowSourceVideo": false,
    "logo": "https://example.com/logo.png",
    "name": "Test Event 2016",
    "quality": "",
    "mobileDisallow": false,
    "mobileAudienceDisallow": false,
    "mobileData": "",
    "mfa": "email"
  },
  "loginToken": {
    "type": "interpreter"
  },
  "sessions": [
    {
      "id": 4,
      "isFloor": false,
      "language": "English",
      "languageCode": "en",
      "mode": "routed",
      "archive": true,
      "tokbox": {
        "sessionId": "1_MX40NT(...)09-fg",
        "sessionToken": "T1==cGF(...)5LWZn"
      }
    },
    {
      "id": 5,
      "isFloor": true,
      "language": "Floor",
      "languageCode": null,
      "mode": "routed",
      "archive": true,
      "tokbox": {
        "sessionId": "2_MX40NTYzODj(...)FR-fg",
        "sessionToken": "T1==cGFy(...)Zmc="
      }
    }
  ]
}

Booking Emails

Required Authentication

Static API Token

POST /bookingemails/

RPC style endpoint to send a booking email.

Required Request Fields

The POST body must contain the following JSON, sent as application/json encoded request:

{
  "event": {    
    "date": "...",    
    "country": "...",    
    "lengthDays": "...",    
    "lengthHoursDay": "...",    
    "amountPeople": "...",    
    "fromLang": "...",    
    "toLang": "...",    
  },    
  "contact": {    
    "name": "...",    
    "position": "...",    
    "company": "...",    
    "phone": "...",    
    "email": "...",    
  }    
}

HTTP Response Codes

• HTTP 204 No Content: E-mail was sent.
• HTTP 400 Bad Request: Some fields are missing.
• HTTP 500 Internal Server Error: E-mail could not be sent.

Network Test Session

Required Authentication

Static API Token

POST /networktestsessions/

RPC style endpoint to generate a new TokBox session for a network test.

curl -X POST -H "Content-Type: application/json" \\
               -H "Authorization: Token d34db33f(...)" \\
               http://localhost:8001/api/v2/networktestsession/
    HTTP/1.0 201 CREATED
    Content-Type: application/json

    {
       "sessionId": "2_MX40Njk0OTEwNH5-(...))",
       "sessionToken": "T1==cGFydG5lcl9pZ(...)
    }
  

The response contains the session information.