Authentication
Basic Auth is very easy and stateless, and most REST clients have built-in support for sending credentials this way.
Access Tokens will greatly reduce the number of times your password is transmitted (even though it is TLS). Also, the server will also respond faster if you use Access Tokens because it doesn't have to BCrypt your password for each request.
You can provide either your Relay username and password or your Seam username and password. If you're requesting a Relay Access Token, you may also provide a Seam Enterprise Admin Access Token instead of username and password.
Basic Auth
First, encode your Relay or Seam credentials with Base64.
base64("myusername:mypassword") → "bXl1c2VybmFtZTpteXBhc3N3b3Jk"
Then, in each request, include a Basic Auth header with these credentials.
GET https://relay.bluejeans.com/api/endpoints HTTP/1.1
Authorization: Basic bXl1c2VybmFtZTpteXBhc3N3b3Jk
Access Token from Username and Password
First, generate a Basic Auth header using your Relay or Seam username and password.
Next, use that Basic Auth header to create an Access Token.
POST https://relay.bluejeans.com/api/auth/accesstokens HTTP/1.1
Authorization: Basic bXl1c2VybmFtZTpteXBhc3N3b3Jk
HTTP/1.1 200 OK
{ "enterpriseName": "myenterprise", "accessToken": "DFG67SD876DFG76SDF5", "creationDate": 1418375348052, "expirationDate": 1419584948052, "roles": ["ROLE_READWRITE", "ROLE_READONLY"], "clientName": null }
Finally, include the accessToken string in future requests. You can pass it as a query parameter or as a header.
At this point, the Basic Auth header is no longer needed and should not be sent with requests.
GET https://relay.bluejeans.com/api/endpoints?accesstoken=DFG67SD876DFG76SDF5 HTTP/1.1
GET https://relay.bluejeans.com/api/endpoints HTTP/1.1
X-Access-Token: DFG67SD876DFG76SDF5
Access Tokens expire after two weeks by default, at which point you can repeat this process to create another token. You may also specify a custom duration with the optional duration query parameter of auth.createAccessToken.
Access Token from Seam Access Token
You may exchange an existing Seam User Access Token or Seam Enterprise Access Token for a Relay Access Token.
If you provide a Seam User Access Token for a user that is not an Enterprise Admin, your Relay Access Token will be Read-Only. This will let you read existing provisioning data and control endpoints, but will you will not be able to create, edit, or delete provisioning data.
The steps similar to those in Access Token from Username and Password, but instead of passing a Basic Auth header, you pass a seamaccesstoken query parameter.
POST https://relay.bluejeans.com/api/auth/accesstokens?seamaccesstoken=afaac60079ad41f18f0dd9ff49cdc6dc HTTP/1.1
HTTP/1.1 200 OK
{ "enterpriseName": "myenterprise", "accessToken": "DFG67SD876DFG76SDF5", "creationDate": 1418375348052, "expirationDate": 1419584948052, "roles": ["ROLE_READWRITE", "ROLE_READONLY"], "clientName": null }
Use the resulting token in requests as a query parameter or header, as described above.
GET https://relay.bluejeans.com/api/endpoints?accesstoken=DFG67SD876DFG76SDF5 HTTP/1.1
GET https://relay.bluejeans.com/api/endpoints HTTP/1.1
X-Access-Token: DFG67SD876DFG76SDF5
Access Token for Zero Touch
To create a Zero Touch access token you follow the same steps above with the Seam Access Token and you also pass in an additional code query param which is the pairing code for the Endpoint. A Zero Touch Access Token is valid for 1day.
POST https://relay.bluejeans.com/api/auth/accesstokens?seamaccesstoken=f754583448814a31960a1052df53384f&code=WNRZJ HTTP/1.1
HTTP/1.1 200 OK
{ "accessToken": "r9vp3vrlu47chg9shon87vmd76vpa3nh", "creator": "anonymousUser", "enterpriseName": "myenterprise", "creationDate": 1629158942852, "expirationDate": 1630368542852, "clientName": "my_relay_client_app", "roles": [ "ROLE_PAIRINGCODE" ], "seamId": 783, "pairingCodeId":"611afe8d58320c7828ebd1a7", "pairingCodeEndpointId":"5f8772d7e16c9da04f43df5e", "clientDeviceType":"NATIVE_IOS" }
A user must be setup with the correct feature enablements before they can start using Zero Touch.
Only these APIs are available to be used with Zero Touch Access Tokens by using the properties; pairingCodeId, pairingCodeEndpointId, accessToken where appropriate, and should generally be used in this order after successfully creating an Access Token:
- GET /api/endpoints/:pairingCodeId/pairingcode Get more information about the Endpoint such as name and capabilities.
- GET /api/meetings/?endpoint=:pairingCodeEndpointId Get the list of meetings on the Endpoint.
- GET /api/meetings/:meetingId/joinflow Pre-join check for a meeting.
- POST /api/endpoints/:pairingCodeEndpointId/join Join a meeting.
- GET /api/endpoints/:pairingCodeEndpointId/status Periodically use this API to check for Endpoint updates such as dialing, active and mute states. Recommended poll updates: dialing=2seconds, active=5seconds, inactive=20seconds.
- GET /api/endpoints/:pairingCodeEndpointId/paired Check who is currently paired with the Endpoint.
- POST /api/endpoints/:pairingCodeEndpointId/mutemicrophone When the Endpoint is in an active call use this API to natively mute the Endpoint.
- POST /api/endpoints/:pairingCodeEndpointId/unmutemicrophone When the Endpoint is in an active call use this API to natively unmute the Endpoint.
- POST /api/endpoints/:pairingCodeEndpointId/hangup When the Endpoint is in an active call use this API to hangup the Endpoint.
- DELETE /api/auth/accesstokens/:accessToken When unpairing the Endpoint use this API to delete the Access Token.
When Access Tokens for Zero Touch are used with the APIs above that use the query params :pairingCodeId or :pairingCodeEndpointId a PairedStatus object will be created or updated for that user that can be viewed using the GET /api/endpoints/:pairingCodeEndpointId/paired API. When the Access Token is deleted or after a 1minute interval with no updates this PairedStatus object will be removed.