Description
You have to call this method when you want to log in an user in your application with DRUID.
If you successfully log in an user in DRUID, you will receive an access_token (that you could use to call other resources that need an user session); you also get all information of the logged user.
Please, read first: https://dru-id.com/developers/apis/oauth-2/ to learn about Oauth2 protocol and the meaning of each token.
Endpoint URL:
POST https://{your-endpoint-domain.com}/activityid/v1/user/access
Request parameters
| Parameter | Description | Type | Required |
|---|---|---|---|
| Authorization | “Bearer app_token” Literal text Bearer followed by app_token that is the token obtained from /oauth2/token endpoint | string | yes |
| Content-Type | The type of content that will be used for requests to be JSON | string | yes |
| Accept | The type of content that will be used for responses to be JSON | string | yes |
| From | Name of the entry point | string | yes |
| Accept-Language | Language for this request | Locale | no |
Query string parameters
| Parameter | Description | Type | Required | Default value |
|---|---|---|---|---|
| sc | With this paramater you can configure how user fields are validated: by default ALL validation errors are returned back to service caller (). If you want to receive only ONE validation error each time, you have to send query String parameter ‘sc=true’ | boolean | no | false |
| fca | Force to check complete account after successful login. If user needs to complete data you will receive same response defined in complete account error each time, you have to send query String parameter ‘sc=true’ | boolean | no | false |
Request example
| Parameter | Description | Type | Required | Value |
|---|---|---|---|---|
| actor.id | app_id of the application you are using to log user | string | yes | app id |
| actor.objectType | Type of the object which represents the actor. | string | yes | ‘application’ |
| verb | Verb used for the login | string | yes | ‘access’ |
| object.objectType | ObjectType represents the user | string | yes | ‘user’ |
| object.password | Password of the user. it must be send plain | string | yes | user password |
| object.ids.email | Structure of email identifier. node name must be “email” | struct | yes | |
| object.ids.email.objectType | ObjectType represents the id of the user | string | yes | ‘user_id’ |
| object.ids.email.value | Email value | string | yes | |
| source.id | Type of device doing the activity | string | yes | ‘unknown’ | ‘pc’ | ‘mobile’ | ‘tablet’ | ‘game_console’ | ‘itv’ |
| source.objectType | Type of source | string | yes | ‘device’ |
Response examples
Response: user logged
| Parameter | Description | Type |
|---|---|---|
| content | Data receive with the response | struct |
| content.user | Data of the user logged with the request. More info about user struct at User Info | struct |
| content.session_info | session info structure | struct |
| content.session_info.access_token | access token value | string |
| content.session_info.token_type | token type | ‘bearer’ |
| content.session_info.expires_in | the remaining lifetime in seconds of the access token | long |
| content.session_info.expires_at | epoch time in milliseconds when the token will expire. If you use unix tools to convert time you must discard last 3 digits | long |
| content.session_info.refresh_token | Refresh token value. You must use if youre are following “oauth2 refresh token flow”. You can ignore this value in rest of cases | string |
| content.session_info.login_status | oauth2 server login status of logged user | struct |
| content.session_info.login_status.uid | DRUID of the logged user.It will have the same value of content.user.id | long |
| content.session_info.login_status.connect_state | oauth2 server connect state | ‘connected’ | ‘notConnected’ | ‘unknown’ |
| content.session_info.scope | scope for which the token was created | string |
| result.status | http status code | integer |
Response: user login success, but need to complete data
This request is made with request parameter fca=true
| Parameter | Description | Type |
|---|---|---|
| content | Data receive with the response | struct |
| content.user | Data of the user logged with the request. More info about user struct at User Info | struct |
| content.session_info | session info structure | struct |
| content.session_info.access_token | access token value | string |
| content.session_info.token_type | token type | ‘bearer’ |
| content.session_info.expires_in | the remaining lifetime in seconds of the access token | long |
| content.session_info.expires_at | epoch time in milliseconds when the token will expire. If you use unix tools to convert time you must discard last 3 digits | long |
| content.session_info.refresh_token | Refresh token value. You must use if youre are following “oauth2 refresh token flow”. You can ignore this value in rest of cases | string |
| content.session_info.login_status | oauth2 server login status of logged user | struct |
| content.session_info.login_status.uid | DRUID of the logged user.It will have the same value of content.user.id | long |
| content.session_info.login_status.connect_state | oauth2 server connect state | ‘connected’ | ‘notConnected’ | ‘unknown’ |
| content.session_info.scope | scope for which the token was created | string |
| result.status | http status code | integer |
| result.elapsed | Time spent to receive the response | integer |
| errors | Response errors | struct |
| errors.message | Errors message | string |
| errors.details | Errors detail | string |
Response KO: Terms & Conditions not approved by the user
| Parameter | Description | Type |
|---|---|---|
| content | Data receive with the response | struct |
| content.url | Redirect url to access | string |
| content.assertions | Struct for assertions | struct |
| content.assertions.objectType | ObjectType representing the assertions struct. Will be “assertions” | string |
| content.assertions.items | List of assertions | array |
| content.assertions.items[n].objectType | ObjectType representing the assertion. Will be “assertion” | string |
| content.assertions.items[n].displayName | Text message with the detail ot the assertion and the reference to show to the user | string |
| content.assertions.items[n].type | Assertion type | string |
| content.assertions.items[n].mandatory | Define if assertion is mandatory: user MUST accept assertions that are mandatory | boolean |
| content.assertions.items[n].typology | Tipology of the assertion | string |
| content.assertions.items[n].property | Property of the assertion | string |
Response: User not logged. The user hasn’t been confirmed
| Parameter | Description | Type |
|---|---|---|
| content | Data receive with the response | struct |
| content.url | Redirect url to access to send the confirm code to the user | string |
Response codes
| Code | Type | Description |
|---|---|---|
| 400 | Error | Bad Request: The request could not be understood by the server due to malformed syntax |
| 401 | Error | Unauthorized: authentication is required and has failed or has not yet been provided (token is invalid, etc) |
| 403 | Error | Forbidden: user id or password are invalid |
| 412 | Error | Precondition failed: User can not log because he/she has not confirmed email |
| 451 | Error | Unavailable For Legal Reasons: user must accept new terms and conditions |
| 500 | Error | Internal Server Error: The server encountered an unexpected condition which prevented it from fulfilling the request |
| 504 | Error | Gateway TimeoutService can not contact with oauth server to do some internal operations |
| 200 | Success | User logged successfully. You will get ‘user logged JSON response’ |
| 206 | Success | Partial content: User logged successfullybut needs some data to be completed |