A user can have multiple unique "tokens" which are used to identify the user. Examples of such tokens include an e-mail address, phone number, or an OAuth provider. A user can login with any of the tokens. At least one token is mandatory for authentication, besides in one notable case...
It is also possible to login via a guest_id
. If a vAtom is sent to a user that is not recognized by our API,
a "guest user" is created for them along with a guest_id
token that is typically sent to them via email or SMS. The user can then login with their guest_id
and set a password via the Update Profile endpoint to remove the guest authentication.
Content-Type: application/json
App-Id: {app_id}
Name | Type | Description |
---|---|---|
token | string | The value of the token, for example
john.doe@example.com |
token_type
*
| string | The type of the token, for example
email
. |
auth_data | object | Contains the data that is used for authentication. |
The data that is required for authentication depends on the type of token used for authentication.
phone
and email
tokens must be authenticated via a password
string.
oauth
token types are authenticated via an oauth_token
string that is verified with a third party provider.
{
"token" : "john.doe@example.com",
"token_type" : "email",
"auth_data" : {
"password": "secret"
}
}
{
"token" : "+11234567890",
"token_type" : "phone_number",
"auth_data" : {
"password": "secret"
}
}
{
"token" : "afd437ec-83c5-4b7f-b3fd-ceead09101bc",
"token_type" : "guest_id"
}
When logging in via Facebook, the token is omitted in the request since it will be returned by the Facebook OAuth flow.
Instead the oauth_token
received from Facebook as part of the oAuth flow is submitted. The oauth_token
will then be used
to call the Facebook API and find the matching ID returned by Facebook.
{
"token_type" : "facebook",
"auth_data" : {
"oauth_token": "CAAKufIJSLC0BAEyrQkyFsCb2ziiwa...."
}
}
On successful authentication two JWTs (RFC 7519) will be returned as part of the HTTP response body:
access_token
- This token MUST be passed as Bearer (scheme) token in the HTTP Authorization
header. It is not an OAuth token even though the naming convention matches OAuth's. This token will be valid for 5 minutes after the login request is made.refresh_token
- This token is for used to Refresh the Access Token.Error | Type | Description |
---|---|---|
200 | http | Everything is OK |
400 | http | Bad Request |
403 | http | Not Authorized |
Name | Type | Description |
---|---|---|
user | object | The user object that was created. |
[
asset_provider
] | array | An array of
asset_provider
objects. |
access_token | string | A JWT access token according to RFC 7519, which will be valid for 5 minutes. |
refresh_token | string | A refresh token used to request a new access token. |
{
"payload": {
"user": {
"id": "001d0933-88e6-4e17-b147-0f672dc016d1",
"meta": {
"data_type": "blockv::user",
"when_created": "2018-01-01T00:00:00+00:00",
"when_modified": "2018-01-01T00:00:00+00:00"
},
"properties": {
"first_name": "John",
"last_name": "Doe",
"name_public": false,
"avatar_uri": "http://example.com/mypic.jpg",
"avatar_public": false,
"birthday": "1970-01-01",
"nonpush_notification": false,
"language": "en"
},
"system_properties": {
"pub_fqdn": "publisher_fqdn",
"is_admin": false,
"activated": false,
"last_login": "",
"is_merchant": false,
}
},
"asset_provider": [
{
"name": "blockv",
"type": "Cloudfront",
"descriptor": {
"CloudFrontPolicy": "eyJTdGF0ZW1lbnQi...",
"CloudFronSignature": "HEroZOBNqC4ld...",
"CloudFrontKeyPairId": "APKAIB7W534.."
}
}
],
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6...",
"refresh_token": "APHpa3JD9XwQ2DqISfq8YtnVPQUn..."
}
}
{
"user_id": "29828993-c2b4-4f6b-a289-f4bdd965d068",
"pub_fqdn": "publisher_fqdn",
"is_admin": true,
"activated": false,
"exp": 1518020257,
"jti": "ab2c2eb2-b2a3-4f56-a19b-0af82020f755",
"iss": "ebd04065-41d3-4e30-9844-24c594f6b17f",
"sub": "access"
}