...
...
...
...
...
...
| Panel | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||
ON THIS PAGE
|
...
| Note | ||
|---|---|---|
| ||
The BSN user model distinguishes between "persons" and "users":
This system user model allows persons who belong to multiple networks to log in to them using a single set of credentials. In many cases, it also requires two token-authentication requests, as described below. |
...
- The client application makes a POST call to the
/tokenendpoint. The POST body includes , among other parameters, a ausernameandpasswordpair entered by the user.- If the user entered the network name along with his or her their username and password, the client application includes the network name in the
username(e.g."username=exampleNetwork/exampleUser@brightsign.biz"). Otherwise, the network will need to be specified in a second POST call (see step 2a below).
- If the user entered the network name along with his or her their username and password, the client application includes the network name in the
- If the credentials are valid, the server returns code 200 with a response body that includes
access_token,expires_in, andrefresh_tokenvalues.- If a network name was not specified in step 1, the response body will also include a
networkNamesarray that lists networks associated with the specifiedusername. The client application provides the list of networks to the user and allows him or her to select one. It then makes a second POST to the/tokenendpoint with network name included in theusername(e.g."username=exampleNetwork/exampleUser@brightsign.biz").
- If a network name was not specified in step 1, the response body will also include a
- If less than half of the
expires_intime has elapsed (in seconds), and the client application has retained theaccess_tokenvalue in local storage, it includes theaccess_tokenin the "Authorization" header of each request to a BSN endpoint. The value of the "Authorization" header is specified as "Bearer {token_value}".- If more than half of the
expires_intime has elapsed, or if theaccess_tokenis not located in local storage, the client application makes a POST call to the/tokenendpoint with therefresh_tokenvalue. - If the
refresh_tokenis not located in local storage, or if theexpires_intime has elapsed (indicated by a 401 return from the server), the application indicates to the user that access to the BSN connection has been dropped (without loss of unsaved user data). It then prompts the user to enter access credentials again and returns to step 1 of the authentication process.
- If more than half of the
| Note | ||
|---|---|---|
| ||
The |
/token
POST
Posts user credentials or a refresh token to the /token endpoint. If the credentials are valid, the server returns an access/refresh token that is included with all other BSN REST calls for authentication.
| Note | ||
|---|---|---|
| ||
Unlike other BSN REST endpoints, the |
...
None
Request Body
username: The BSN username. If this is a User Authentication Request, the network name preceeds the username (e.g. "exampleNetwork/exampleUser@brightsign.biz").password: The password associated with the username.network: The network to which the returned token should grant access. This entry can can be used for either the initial User Authentication Request, or to switch to another network to which that the user belongs to upon token renewal.grant_type: The type of grant being presented in exchange for the access token. This value must be set to"password".client_id: The client identifier. This value is currently not used by the server.client_secret: The client secret. This value is currently not used by the server.refresh_token: The refresh token to include when renewing the access token. When therefresh_tokenentry is included, thepassworddoes not need to be used.
...
[string] access_token: The authorization token to use with endpoint calls until half of theexpires_intime period has elapsed[string] token_type: The OAuth 2.0 token type, which will always be returned as"bearer"[integer] expires_in: The lifetime (in seconds) of the authorization token[string] refresh_token: The token to use for re-authentication when more than half of theexpires_intime period has elapsed.[string[]]scope: An array that lists the scope granted by the token. A successful Person Authentication Response will include the"Self"value only, while a successful User Authentication Response will contain both"Full"and"Self"values.[string] userLogin: Theusernameincluded in the request body[integer] userId: The user identifier, which may be used in subsequent requests. This entry is only returned for User Authentication Requests.[integer] personId: The person identifier[string[]] networkNames: An array of networks to which the person (i.e. the account associated with the login credentials) belongs. This entry is only returned for Person Authentication requests.[string] .issued: The date and time the authorization/refresh token was issued (formatted as"[3-letter weekday], dd mmm yyyy hh:mm:ss [3-letter timezone]")[string] .expires: The date and time the authorization/refresh token expires (formatted as"[3-letter weekday], dd mmm yyyy hh:mm:ss [3-letter timezone]")
Examples
Person Authentication Request
...
The client application makes this authorization request when it has the network name, which can be retrieved either from user entry or from a Person Authentication Request. Note that the response body includes the roleName parameter, which allows the client application to determine the permissions scope and available functionality for the user.
...