User and Identity
User and Identity bounded context aka User&Identity.
JSON Web Token
User&Identity uses for authentication JWT:
JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed.
Special roles
User&Identity uses special roles to protec specific end-points, for example to create invitation or fetch user information.
| Role | Description |
|---|---|
| uai_admin | Can create invitations, prototype users. Enable/disable users. Read Users. |
| uai_user_manager | Can create and manage users. Only internal users will be created. |
| uai_invitation_manager | Can create invitations. |
Sample journies
Invite a user:
Create a prototype user, create an invitation to him and redeem the invitation.
-
POST
/user-prototypes -
POST
/user-prototypes/{id}/invitations -
PUT
/invitations/{id}/redemption
Login:
Login to retrieve a token, verify token and refresh for a new one.
-
POST
/authentications -
GET
/me -
POST
/authentications/me/refresh
Login using google Oauth:
-
GET
/authentications/google?redirect_uri=http://bff.spotahome.com/google/check&state=aabbccdd45nnaa -
Authenticate inside google using the authorization URL from the step 1.
-
POST
authentications/googlewith the authorizationcode,redirect_uriandstate.
Disable and enable a user:
-
DELETE
/users/{id}/enabling -
PUT
/users/{id}/enabling
Update user’s email and information by an admin:
-
PUT
/admin/users/{id}/email -
PUT
/admin/users/{id}/information
Update user’s email by the user himself:
-
POST
/me/email-change -
PUT
/email/verification/{checksum}
Update user’s information by the user himself:
- PUT
/me/information
Forget password
Request a new password, get the link and set the new password
-
POST
/forgotten-passwords -
GET
/forgotten-passwords/{id} -
PUT
/forgotten-passwords/{id}/password
Create user with password account
Create a user with password, get the link and activate the account.
-
POST
/signup -
GET
/users/activation/{id} -
POST
/authentications
Invitations ¶
Invitation ¶
Get invitationGET/invitations/{id}
Authorization: protected for uai_admin roles.
Example URI
GET https://user-identity.spotahome.com/invitations/68a5sdf67
URI Parameters
- id
string(required) Example: 68a5sdf67The invitation ID
Response
200Headers
Content-Type: application/jsonBody
{
"id": "68a5sdf67",
"userId": "98uhy65rf",
"createdAt": "2004-02-12T15:20:18+00:00",
"isRedeemed": true,
"redeemedAt": "2004-02-12T15:20:21+00:00",
"emailSentAt": "2004-02-12T15:19:21+00:00",
"isEmailSent": true,
}Response
401Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request requires user authentication",
"status": 401,
"title": "Unauthorized",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains the error code and the description"
}
}
}Response
404Headers
Content-Type: application/problem+jsonBody
{
"detail": "Resource not found",
"status": 404,
"title": "Not found",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
}
}
}Reedem invitation ¶
Redeem invitationPUT/invitations/{id}/redemption
Redeem the invitation to finish the creation of a user.
Example URI
PUT https://user-identity.spotahome.com/invitations/68a5sdf67/redemption
URI Parameters
- id
string(required) Example: 68a5sdf67The invitation ID
Request
Headers
Content-Type: application/jsonBody
{
"password": "123456"
}Response
204Headers
Content-Type: application/json
Location: /users/as4fgt56Response
404Headers
Content-Type: application/problem+jsonBody
{
"detail": "Resource not found",
"status": 404,
"title": "Not found",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
}
}
}Response
409Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request could not be completed due to a conflict with the current state of the resource",
"status": 409,
"title": "Conflict",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "the error code and the description."
}
}
}Response
422Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request was well formed but was unable to be followed due to semantic errors",
"status": 422,
"title": "Unprocessable Entity",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains a property for each field that failed validation."
}
}
}Prototype Users ¶
Prototype users ¶
Allow to create new prototype user, with no password, so this user can not log in until configure his password.
Authorization: protected for uai_admin role.
Create prototype userPOST/user-prototypes
Example URI
POST https://user-identity.spotahome.com/user-prototypes
Request
Headers
Content-Type: application/json
Authorization: aa.bb.ccBody
{
"fullname": "John Smith",
"email": "user@domain.com",
"locale": "es_ES",
"roles": [
"foo",
"bar"
]
}Response
201Headers
Location: /users/123abcResponse
401Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request requires user authentication",
"status": 401,
"title": "Unauthorized",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains the error code and the description"
}
}
}Response
409Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request could not be completed due to a conflict with the current state of the resource",
"status": 409,
"title": "Conflict",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "the error code and the description."
}
}
}Response
422Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request was well formed but was unable to be followed due to semantic errors",
"status": 422,
"title": "Unprocessable Entity",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains a property for each field that failed validation."
}
}
}Invitations ¶
Create invitationPOST/user-prototypes/{id}/invitations
Invitation for the prototype user, allows to finish the creation of the user account establishing the password.
Authorization: protected for uai_admin, uai_user_manager and uai_invitation_manager roles.
Example URI
POST https://user-identity.spotahome.com/user-prototypes/68a5sdf67/invitations
URI Parameters
- id
string(required) Example: 68a5sdf67The user ID
Request
Headers
Content-Type: application/json
Authorization: aa.bb.ccBody
{
"notify" : true, //default value
"callback_url" : "http://spotahome.com/bff/landlord/invitation/:id"
}Response
201Headers
Location: /invitations/123abcResponse
401Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request requires user authentication",
"status": 401,
"title": "Unauthorized",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains the error code and the description"
}
}
}Response
404Headers
Content-Type: application/problem+jsonBody
{
"detail": "Resource not found",
"status": 404,
"title": "Not found",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
}
}
}Response
409Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request could not be completed due to a conflict with the current state of the resource",
"status": 409,
"title": "Conflict",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "the error code and the description."
}
}
}Response
422Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request was well formed but was unable to be followed due to semantic errors",
"status": 422,
"title": "Unprocessable Entity",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains a property for each field that failed validation."
}
}
}Users ¶
Users ¶
Authorization: protected for uai_admin
Search usersGET/users{role,email,ids,page,itemsPerPage}
Example URI
GET https://user-identity.spotahome.com/usersuai_admin&test@spotahome.com&aaaa&0&10
URI Parameters
- role
string(optional) Example: uai_adminstring(optional) Example: test@spotahome.com- ids
string(required) Example: aaaabbbb-cccc, cccc-aaaa-bbbb (array[string], optional) - Criteria by multiple ids.
- page
number(optional) Example: 0- itemsPerPage
number(optional) Example: 10
Request
Headers
Content-Type: application/json
Authorization: aa.bb.ccResponse
200Headers
Content-Type: application/jsonBody
{
"count": 1,
"total": 2,
"_links": {
"self": {
"href": "users?role=uai_admin&itemsPerPage=1&page=1"
},
"first": {
"href": "users?role=uai_admin&itemsPerPage=1&page=1"
},
"last": {
"href": "users?role=uai_admin&itemsPerPage=1&page=2"
},
"next": {
"href": "users?role=uai_admin&itemsPerPage=1&page=2"
}
},
"_embedded": {
"users": [
{
"id": "5fae5dd4-f575-4461-bda1-d7c9b0227e53",
"email": "fake@spotahome.com",
"roles": [
"uai_admin"
],
"locale": "en",
"fullname": "fake",
"createdAt": "2017-08-24 10:18:30",
"isEnabled": true,
"prototype": false,
"lastAuthenticationAt": null
}
]
}
}Response
401Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request requires user authentication",
"status": 401,
"title": "Unauthorized",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains the error code and the description"
}
}
}User with password signup ¶
This is a public endpoint used by the BFF to create users with required email activation in the website.
Signup UserPOST/signup
Example URI
POST https://user-identity.spotahome.com/signup
Request
Headers
Content-Type: application/json
Authorization: aa.bb.ccBody
{
"fullname": "John Smith",
"email": "user@domain.com",
"password": "12345678",
"activation_callback_url": "http://spotahome.com/bff/users/activation/:id",
"locale": "en",
"role": "uai_role"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"fullname": {
"type": "string"
},
"email": {
"type": "string"
},
"password": {
"type": "string"
},
"activation_callback_url": {
"type": "string"
},
"locale": {
"type": "string"
},
"role": {
"type": "string"
}
},
"required": [
"fullname",
"email",
"password",
"activation_callback_url",
"locale"
]
}Response
201Headers
Location: /users/68a5sdf67Response
409This happens when a user with the same email already exists.
The content of the validationMessages fields is always email.emailAlreadyInUse
Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request could not be completed due to a conflict with the current state of the resource",
"status": 409,
"title": "Conflict",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"email": {
"emailAlreadyInUse": "Email already in use"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"email": {
"type": "object",
"properties": {
"emailAlreadyInUse": {
"type": "string"
}
}
}
},
"description": "the error code and the description."
}
}
}Response
422Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request was well formed but was unable to be followed due to semantic errors",
"status": 422,
"title": "Unprocessable Entity",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"fullname": {
"stringLengthTooShort": "The input is less than 4 characters long"
},
"email": {
"emailAddressInvalidFormat": "The input is not a valid email address. Use the basic format local",
"emailDomainNotAllowed": "The email hola@spotahome.com cannot be a tenant!"
},
"password": {
"stringLengthTooShort": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"fullname": {
"type": "object",
"properties": {
"stringLengthTooShort": {
"type": "string"
}
}
},
"email": {
"type": "object",
"properties": {
"emailAddressInvalidFormat": {
"type": "string",
"description": "part@domain"
},
"emailDomainNotAllowed": {
"type": "string"
}
}
},
"password": {
"type": "object",
"properties": {
"stringLengthTooShort": {
"type": "string"
}
}
}
},
"description": "Contains a property for each field that failed validation."
}
}
}User ¶
Create social userPOST/users
Create social users for the backoffice.
Authorization: protected for uai_admin roles and/or the user himself.
Example URI
POST https://user-identity.spotahome.com/users
Request
Headers
Content-Type: application/json
Authorization: aa.bb.ccBody
{
"fullname": "John Smith",
"email": "user@domain.com",
"locale": "en",
"roles": [
"uai_employee",
"bookings_bonsai_edit"
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"fullname": {
"type": "string"
},
"email": {
"type": "string"
},
"locale": {
"type": "string"
},
"roles": {
"type": "array"
}
},
"required": [
"fullname",
"email",
"locale",
"roles"
]
}Response
201Headers
Location: /users/68a5sdf67Response
401Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request requires user authentication",
"status": 401,
"title": "Unauthorized",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains the error code and the description"
}
}
}Response
422Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request was well formed but was unable to be followed due to semantic errors",
"status": 422,
"title": "Unprocessable Entity",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains a property for each field that failed validation."
}
}
}Get user by idGET/users/{id}
Retrieve user information
Authorization: protected for uai_admin, uai_employee and uai_user_manager role
Example URI
GET https://user-identity.spotahome.com/users/68a5sdf67
URI Parameters
- id
string(required) Example: 68a5sdf67The user ID
Request
Headers
Content-Type: application/json
Authorization: aa.bb.ccResponse
200Headers
Content-Type: application/jsonBody
{
"id": "68a5sdf67",
"fullname": "John Smith",
"locale": "es_ES",
"roles": [
"foo",
"bar"
],
"email": "user@domain.com",
"createdAt": "2004-02-12T15:20:21+00:00",
"lastAuthenticationAt": "2004-02-12T15:20:21+00:00",
"isEnabled": true
}Response
401Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request requires user authentication",
"status": 401,
"title": "Unauthorized",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains the error code and the description"
}
}
}Response
404Headers
Content-Type: application/problem+jsonBody
{
"detail": "Resource not found",
"status": 404,
"title": "Not found",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
}
}
}Get user by tokenGET/users/me
Example URI
GET https://user-identity.spotahome.com/users/me
Request
Headers
Content-Type: application/json
Authorization: aa.bb.ccResponse
200Headers
Content-Type: application/jsonBody
{
"id": "68a5sdf67",
"fullname": "John Smith",
"locale": "es_ES",
"roles": [
"foo",
"bar"
],
"email": "user@domain.com",
"createdAt": "2004-02-12T15:20:21+00:00",
"lastAuthenticationAt": "2004-02-12T15:20:21+00:00",
"isEnabled": true
}Response
401Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request requires user authentication",
"status": 401,
"title": "Unauthorized",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains the error code and the description"
}
}
}Validate user on critical actionsGET/users/me/verify
Validate user on critical actions and do not rely on JWT expiration date.
Example URI
GET https://user-identity.spotahome.com/users/me/verify
Request
Headers
Content-Type: application/json
Authorization: aa.bb.ccResponse
204Headers
Content-Type: application/jsonResponse
401Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request requires user authentication",
"status": 401,
"title": "Unauthorized",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains the error code and the description"
}
}
}Response
403Headers
Content-Type: application/problem+jsonBody
{
"detail": "User '00000000",
"status": 403,
"title": "Forbidden",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "0000-0000-0000-000000000000' cannot impersonate as '11111111-1111-1111-1111-111111111111' (string)"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
}
}
}Enable / Disable ¶
Ability to avoid users to login.
Authorization: protected for uai_admin roles.
EnablePUT/users/{id}/enabling
Example URI
PUT https://user-identity.spotahome.com/users/68a5sdf67/enabling
URI Parameters
- id
string(required) Example: 68a5sdf67The user ID
Request
Headers
Content-Type: application/json
Authorization: aa.bb.ccResponse
204Response
400Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request was well formed but was unable to be followed due to semantic errors",
"status": 400,
"title": "Bad Request",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains a property for each field that failed validation."
}
}
}Response
401Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request requires user authentication",
"status": 401,
"title": "Unauthorized",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains the error code and the description"
}
}
}Response
404Headers
Content-Type: application/problem+jsonBody
{
"detail": "Resource not found",
"status": 404,
"title": "Not found",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
}
}
}DisableDELETE/users/{id}/enabling
Example URI
DELETE https://user-identity.spotahome.com/users/68a5sdf67/enabling
URI Parameters
- id
string(required) Example: 68a5sdf67The user ID
Request
Headers
Content-Type: application/json
Authorization: aa.bb.ccResponse
204Response
401Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request requires user authentication",
"status": 401,
"title": "Unauthorized",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains the error code and the description"
}
}
}Response
404Headers
Content-Type: application/problem+jsonBody
{
"detail": "Resource not found",
"status": 404,
"title": "Not found",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
}
}
}Activation ¶
Activate userPUT/users/activation/{activationCode}
When a user with password is created in the website, an activation email is sent to the user’s email. This endpoint will be executed when the user tries to open the link in the email in order to activate the account (aka validating the email).
Example URI
PUT https://user-identity.spotahome.com/users/activation/68a5sdf67
URI Parameters
- activationCode
string(required) Example: 68a5sdf67The activation code associated to the user.
Request
Headers
Content-Type: application/jsonResponse
204Headers
Location: /users/123abcResponse
404Headers
Content-Type: application/problem+jsonBody
{
"detail": "Resource not found",
"status": 404,
"title": "Not found",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
}
}
}Resend activationPOST/users/activation/{id}
Resend activation link by email that was already created.
Example URI
POST https://user-identity.spotahome.com/users/activation/68a5sdf67
URI Parameters
- id
string(required) Example: 68a5sdf67The user ID
Request
Headers
Content-Type: application/jsonBody
{
"activation_callback_url": "http://spotahome.com/bff/users/activation/:id"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"activation_callback_url": {
"type": "string"
}
},
"required": [
"activation_callback_url"
]
}Response
204Response
404Headers
Content-Type: application/problem+jsonBody
{
"detail": "Resource not found",
"status": 404,
"title": "Not found",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
}
}
}Add / Remove set of roles ¶
Ability to add or remote roles from a specific user.
Authorization: protected for uai_admin roles.
AddPOST/users/{id}/roles
Add a specific role to a user.
Example URI
POST https://user-identity.spotahome.com/users/68a5sdf67/roles
URI Parameters
- id
string(required) Example: 68a5sdf67The user ID
Request
Headers
Content-Type: application/json
Authorization: aa.bb.ccBody
{
"role": "bookings_bonsai_edit"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"role": {
"type": "string"
}
},
"required": [
"role"
]
}Response
204Response
401Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request requires user authentication",
"status": 401,
"title": "Unauthorized",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains the error code and the description"
}
}
}Response
404Headers
Content-Type: application/problem+jsonBody
{
"detail": "Resource not found",
"status": 404,
"title": "Not found",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
}
}
}Response
409Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request could not be completed due to a conflict with the current state of the resource",
"status": 409,
"title": "Conflict",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "the error code and the description."
}
}
}Response
422Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request was well formed but was unable to be followed due to semantic errors",
"status": 422,
"title": "Unprocessable Entity",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains a property for each field that failed validation."
}
}
}RemoveDELETE/users/{id}/roles/{role}
Remove a specific role to a User.
Example URI
DELETE https://user-identity.spotahome.com/users/68a5sdf67/roles/bookings_bonsai_edit
URI Parameters
- id
string(required) Example: 68a5sdf67The user ID
- role
string(required) Example: bookings_bonsai_edit
Request
Headers
Content-Type: application/json
Authorization: aa.bb.ccResponse
204Response
401Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request requires user authentication",
"status": 401,
"title": "Unauthorized",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains the error code and the description"
}
}
}Response
404Headers
Content-Type: application/problem+jsonBody
{
"detail": "Resource not found",
"status": 404,
"title": "Not found",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
}
}
}Impersonation ¶
Impersonate as another userPOST/users/{id}/impersonate
Creates a JWT token with the user’s data, and a new impersonated_user_id attribute in the payload. Currently, these impersonations are allowed:
-
Role
uai_admincan impersonate any user that isn’t auai_admin. This means, admins can impersonate as any non-admin user. -
Role
ROLE_PROPERTY_ACQUISITION_AGENTcan impersonate as a user with the roleROLE_ACCOMMODATION_PROVIDER. This means agents can impersonate as landlords.
Example URI
POST https://user-identity.spotahome.com/users/68a5sdf67/impersonate
URI Parameters
- id
string(required) Example: 68a5sdf67The user ID who will be impersonated
Request
Headers
Content-Type: application/json
Authorization: aa.bb.ccResponse
201Headers
Content-Type: application/jsonBody
{
"jwt": "aa.bb.cc",
"accessToken": "aa.bb.cc",
"refreshToken": "dd.ee.ff"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"jwt": {
"type": "string",
"description": "Deprecated field. Use accessToken instead, it has same value."
},
"accessToken": {
"type": "string",
"description": "The access token to use for access to APIs."
},
"refreshToken": {
"type": "string",
"description": "The refresh token to use for request new access tokens"
}
}
}Response
403Headers
Content-Type: application/problem+jsonBody
{
"detail": "User '00000000",
"status": 403,
"title": "Forbidden",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "0000-0000-0000-000000000000' cannot impersonate as '11111111-1111-1111-1111-111111111111' (string)"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
}
}
}Response
404Headers
Content-Type: application/problem+jsonBody
{
"detail": "Resource not found",
"status": 404,
"title": "Not found",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
}
}
}Update User's email ¶
Updates user’s email by an admin user.
Authorization: protected for uai_admin roles.
Admin update emailPUT/admin/users/{id}/email
Example URI
PUT https://user-identity.spotahome.com/admin/users/68a5sdf67/email
URI Parameters
- id
string(required) Example: 68a5sdf67The user ID
Request
Headers
Content-Type: application/json
Authorization: aa.bb.ccBody
{
"email" : "user@domain.com",
"notify" : true // default value
}Response
204Response
401Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request requires user authentication",
"status": 401,
"title": "Unauthorized",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains the error code and the description"
}
}
}Response
404Headers
Content-Type: application/problem+jsonBody
{
"detail": "Resource not found",
"status": 404,
"title": "Not found",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
}
}
}Response
409Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request could not be completed due to a conflict with the current state of the resource",
"status": 409,
"title": "Conflict",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "the error code and the description."
}
}
}Response
422Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request was well formed but was unable to be followed due to semantic errors",
"status": 422,
"title": "Unprocessable Entity",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains a property for each field that failed validation."
}
}
}Update User's information ¶
Updates user’s fullname and locale by an admin user
Authorization: protected for uai_admin roles.
Admin update informationPUT/admin/users/{id}/information
Example URI
PUT https://user-identity.spotahome.com/admin/users/68a5sdf67/information
URI Parameters
- id
string(required) Example: 68a5sdf67The user ID
Request
Headers
Content-Type: application/json
Authorization: aa.bb.ccBody
{
"fullname": "John Snow",
"locale": "es"
}Response
204Response
401Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request requires user authentication",
"status": 401,
"title": "Unauthorized",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains the error code and the description"
}
}
}Response
404Headers
Content-Type: application/problem+jsonBody
{
"detail": "Resource not found",
"status": 404,
"title": "Not found",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
}
}
}Response
422Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request was well formed but was unable to be followed due to semantic errors",
"status": 422,
"title": "Unprocessable Entity",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains a property for each field that failed validation."
}
}
}User request email's change ¶
Create a request for changing the user’s email. Send by the user himself
Authorization: protected for user (user token).
User request email's changePOST/me/email-change
Example URI
POST https://user-identity.spotahome.com/me/email-change
Request
Headers
Content-Type: application/json
Authorization: aa.bb.ccBody
{
"email": "user@domain.com",
"callback_url": "http://spotahome.com/bff/landlord/email/:id"
}Response
204Response
401Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request requires user authentication",
"status": 401,
"title": "Unauthorized",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains the error code and the description"
}
}
}Response
404Headers
Content-Type: application/problem+jsonBody
{
"detail": "Resource not found",
"status": 404,
"title": "Not found",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
}
}
}Response
409Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request could not be completed due to a conflict with the current state of the resource",
"status": 409,
"title": "Conflict",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "the error code and the description."
}
}
}Response
422Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request was well formed but was unable to be followed due to semantic errors",
"status": 422,
"title": "Unprocessable Entity",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains a property for each field that failed validation."
}
}
}Verify User's email change ¶
Verify the email change’s request and update the user’s email
User update emailPUT/email/verification/{checksum}
Example URI
PUT https://user-identity.spotahome.com/email/verification/abcabcabcabcabcabc
URI Parameters
- checksum
string(required) Example: abcabcabcabcabcabcThe user ID
Request
Headers
Content-Type: application/jsonResponse
204Response
404Headers
Content-Type: application/problem+jsonBody
{
"detail": "Resource not found",
"status": 404,
"title": "Not found",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
}
}
}Response
409Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request could not be completed due to a conflict with the current state of the resource",
"status": 409,
"title": "Conflict",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "the error code and the description."
}
}
}Response
422Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request was well formed but was unable to be followed due to semantic errors",
"status": 422,
"title": "Unprocessable Entity",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains a property for each field that failed validation."
}
}
}Update user information ¶
Update user fullname and locale
Authorization: protected for user (user token).
User updates informationPUT/me/information
Example URI
PUT https://user-identity.spotahome.com/me/information
Request
Headers
Content-Type: application/json
Authorization: aa.bb.ccBody
{
"fullname": "John Snow",
"locale": "en"
}Response
204Response
401Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request requires user authentication",
"status": 401,
"title": "Unauthorized",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains the error code and the description"
}
}
}Response
404Headers
Content-Type: application/problem+jsonBody
{
"detail": "Resource not found",
"status": 404,
"title": "Not found",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
}
}
}Response
422Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request was well formed but was unable to be followed due to semantic errors",
"status": 422,
"title": "Unprocessable Entity",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains a property for each field that failed validation."
}
}
}Forgotten passwords ¶
Forgotten password ¶
CreatePOST/forgotten-passwords
Example URI
POST https://user-identity.spotahome.com/forgotten-passwords
Request
Headers
Content-Type: application/jsonBody
{
"email": "user@domain.com",
"callback_url": "http://spotahome.com/bff/landlord/password/:id"
}Response
201Headers
Location: /forgotten-passwords/68a5sdf67Response
422Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request was well formed but was unable to be followed due to semantic errors",
"status": 422,
"title": "Unprocessable Entity",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains a property for each field that failed validation."
}
}
}Forgotten password ¶
Get forgotten passwordGET/forgotten-passwords/{id}
Example URI
GET https://user-identity.spotahome.com/forgotten-passwords/68a5sdf67
URI Parameters
- id
string(required) Example: 68a5sdf67The forgotten password ID
Response
200Headers
Content-Type: application/jsonBody
{
"expiration_date": "01/01/2000"
}Response
404Headers
Content-Type: application/problem+jsonBody
{
"detail": "Resource not found",
"status": 404,
"title": "Not found",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
}
}
}Forgotten password ¶
Set new passwordPUT/forgotten-passwords/{id}/password
Example URI
PUT https://user-identity.spotahome.com/forgotten-passwords/68a5sdf67/password
URI Parameters
- id
string(required) Example: 68a5sdf67The forgotten password ID
Request
Headers
Content-Type: application/jsonBody
{
"password": "123456"
}Response
204Response
404Headers
Content-Type: application/problem+jsonBody
{
"detail": "Resource not found",
"status": 404,
"title": "Not found",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
}
}
}Response
409Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request could not be completed due to a conflict with the current state of the resource",
"status": 409,
"title": "Conflict",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "the error code and the description."
}
}
}Response
422Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request was well formed but was unable to be followed due to semantic errors",
"status": 422,
"title": "Unprocessable Entity",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains a property for each field that failed validation."
}
}
}Authentication ¶
Authentication ¶
We return a pair of tokens:
-
Access Token: it can be used to access APIs
-
Refresh Token: it can be used to request a new access token
Authenticate a userPOST/authentications
Example URI
POST https://user-identity.spotahome.com/authentications
Request
Headers
Content-Type: application/jsonBody
{
"email": "user@domain.com",
"password": "foo123",
"login_context": "landlord"
}Response
201Headers
Content-Type: application/jsonBody
{
"jwt": "aa.bb.cc",
"accessToken": "aa.bb.cc",
"refreshToken": "dd.ee.ff"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"jwt": {
"type": "string",
"description": "Deprecated field. Use accessToken instead, it has same value."
},
"accessToken": {
"type": "string",
"description": "The access token to use for access to APIs."
},
"refreshToken": {
"type": "string",
"description": "The refresh token to use for request new access tokens"
}
}
}Response
404Headers
Content-Type: application/problem+jsonBody
{
"detail": "Resource not found",
"status": 404,
"title": "Not found",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
}
}
}Response
422This example shows multiple errors in the same body. But only emailAddressInvalidFormat and password’s stringLengthTooShort
can appear at the same time. All other possible values exclude any other error.
Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request was well formed but was unable to be followed due to semantic errors",
"status": 422,
"title": "Unprocessable Entity",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"email": {
"emailAddressInvalidFormat": "The input is not a valid email address. Use the basic format local",
"userNotExists": "This user does not exist",
"authenticationMethodNotSupported": "The authentication method provided cannot be used by this user",
"userIsDisabled": "User is Disabled",
"userIsPrototype": "User is a prototype"
},
"password": {
"stringLengthTooShort": "The input is less than 6 characters long",
"invalidPassword": "The password is invalid"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"email": {
"type": "object",
"properties": {
"emailAddressInvalidFormat": {
"type": "string",
"description": "part@hostname"
},
"userNotExists": {
"type": "string"
},
"authenticationMethodNotSupported": {
"type": "string"
},
"userIsDisabled": {
"type": "string"
},
"userIsPrototype": {
"type": "string"
}
}
},
"password": {
"type": "object",
"properties": {
"stringLengthTooShort": {
"type": "string"
},
"invalidPassword": {
"type": "string"
}
}
}
},
"description": "Contains a property for each field that failed validation."
}
}
}Google ¶
Google authentication follows the Oauth protocol.
Authorization DEPRECATEDGET/authentications/google{?redirect_uri,state}
Generates an authorization url that will be used to redirect the user to authenticate in a google login page.
Example URI
GET https://user-identity.spotahome.com/authentications/google?redirect_uri=http:/bff.spotahome.com/google/check&state=aabbccdd45nnaa
URI Parameters
- redirect_uri
string(optional) Example: http://bff.spotahome.com/google/checkGoogle after authenticating redirects to this url
- state
string(optional) Example: aabbccdd45nnaaCurrent state encoded in base64 (e.g. isSubscribed, locale, etc)
Request
Headers
Content-Type: application/jsonResponse
200Headers
Content-Type: application/jsonBody
{
"authorization_url": "https://accounts.google.com/o/oauth2/auth?state=fe613f8765&scope=email%20openid%20profile&response_type=code&approval_prompt=auto&redirect_uri=%27%27&client_id=dvdunjtfnb.apps.googleusercontent.com&authuser=-1",
"oauth2state": "fe613f87650b568dbb49edcc6edbccfb"
}Response
422Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request was well formed but was unable to be followed due to semantic errors",
"status": 422,
"title": "Unprocessable Entity",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains a property for each field that failed validation."
}
}
}Authentication DEPRECATEDPOST/authentications/google
Authenticates in Google Oauth API and verifies if the account exists and it is enabled. Returns a pair of JWT token if authenticated successfully: access token and refresh token.
Example URI
POST https://user-identity.spotahome.com/authentications/google
Request
Headers
Content-Type: application/jsonBody
{
"code": "fe613f87650b568dbb49e",
"redirect_uri": "http://bff.spotahome.com/google/check",
"login_context": "tenant",
"locale": "en"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"code": {
"type": "string"
},
"redirect_uri": {
"type": "string"
},
"login_context": {
"type": "string",
"description": "Can be of types tenant, landlord or employee"
},
"locale": {
"type": "string",
"description": "Identifies the locale of the user that wants to authenticate"
}
},
"required": [
"code",
"redirect_uri",
"login_context",
"locale"
]
}Response
201Headers
Content-Type: application/jsonBody
{
"jwt": "aa.bb.cc",
"accessToken": "aa.bb.cc",
"refreshToken": "dd.ee.ff"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"jwt": {
"type": "string",
"description": "Deprecated field. Use accessToken instead, it has same value."
},
"accessToken": {
"type": "string",
"description": "The access token to use for access to APIs."
},
"refreshToken": {
"type": "string",
"description": "The refresh token to use for request new access tokens"
}
}
}Response
401Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request requires user authentication",
"status": 401,
"title": "Unauthorized",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains the error code and the description"
}
}
}Response
409Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request could not be completed due to a conflict with the current state of the resource",
"status": 409,
"title": "Conflict",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "the error code and the description."
}
}
}Response
422Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request was well formed but was unable to be followed due to semantic errors",
"status": 422,
"title": "Unprocessable Entity",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains a property for each field that failed validation."
}
}
}AuthenticationPOST/oauth/google
Authenticates in Google Oauth API with an access token and verifies if the account exists and it is enabled. Returns a pair of JWT token if authenticated successfully: access token and refresh token.
Example URI
POST https://user-identity.spotahome.com/oauth/google
Request
Headers
Content-Type: application/jsonBody
{
"access_token": "fe613f87650b568dbb49e",
"login_context": "tenant",
"locale": "en"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"access_token": {
"type": "string"
},
"login_context": {
"type": "string",
"description": "Can be of types tenant, landlord or employee"
},
"locale": {
"type": "string",
"description": "Identifies the locale of the user that wants to authenticate"
}
},
"required": [
"access_token",
"login_context",
"locale"
]
}Response
201Headers
Content-Type: application/jsonBody
{
"jwt": "aa.bb.cc",
"accessToken": "aa.bb.cc",
"refreshToken": "dd.ee.ff"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"jwt": {
"type": "string",
"description": "Deprecated field. Use accessToken instead, it has same value."
},
"accessToken": {
"type": "string",
"description": "The access token to use for access to APIs."
},
"refreshToken": {
"type": "string",
"description": "The refresh token to use for request new access tokens"
}
}
}Response
401Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request requires user authentication",
"status": 401,
"title": "Unauthorized",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains the error code and the description"
}
}
}Response
409Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request could not be completed due to a conflict with the current state of the resource",
"status": 409,
"title": "Conflict",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "the error code and the description."
}
}
}Response
422Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request was well formed but was unable to be followed due to semantic errors",
"status": 422,
"title": "Unprocessable Entity",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains a property for each field that failed validation."
}
}
}Authentication using Google Sing in One TapPOST/oauth/sign-in-google
Verifies the credential from Google One Tap and authenticates the user. Returns a pair of JWT token if authenticated successfully: access token and refresh token.
Example URI
POST https://user-identity.spotahome.com/oauth/sign-in-google
Request
Headers
Content-Type: application/jsonBody
{
"credential": "fjhs97hjklashd123",
"login_context": "tenant",
"locale": "en"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"credential": {
"type": "string"
},
"login_context": {
"type": "string",
"description": "Can be of types tenant, landlord or employee"
},
"locale": {
"type": "string",
"description": "Identifies the locale of the user that wants to authenticate"
}
},
"required": [
"credential",
"login_context",
"locale"
]
}Response
201Headers
Content-Type: application/jsonBody
{
"jwt": "aa.bb.cc",
"accessToken": "aa.bb.cc",
"refreshToken": "dd.ee.ff"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"jwt": {
"type": "string",
"description": "Deprecated field. Use accessToken instead, it has same value."
},
"accessToken": {
"type": "string",
"description": "The access token to use for access to APIs."
},
"refreshToken": {
"type": "string",
"description": "The refresh token to use for request new access tokens"
}
}
}Response
401Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request requires user authentication",
"status": 401,
"title": "Unauthorized",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains the error code and the description"
}
}
}Response
409Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request could not be completed due to a conflict with the current state of the resource",
"status": 409,
"title": "Conflict",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "the error code and the description."
}
}
}Response
422Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request was well formed but was unable to be followed due to semantic errors",
"status": 422,
"title": "Unprocessable Entity",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains a property for each field that failed validation."
}
}
}Facebook ¶
Facebook authentication follows the Oauth protocol.
Authorization DEPRECATEDGET/authentications/facebook{?redirect_uri,state}
Generates an authorization url that will be used to redirect the user to authenticate in a facebook login page.
Example URI
GET https://user-identity.spotahome.com/authentications/facebook?redirect_uri=http:/bff.spotahome.com/facebook/check&state=aabbccdd45nnaa
URI Parameters
- redirect_uri
string(optional) Example: http://bff.spotahome.com/facebook/checkFacebook after authenticating redirects to this url
- state
string(optional) Example: aabbccdd45nnaaCurrent state encoded in base64 (e.g. isSubscribed, locale, etc)
Request
Headers
Content-Type: application/jsonResponse
200Headers
Content-Type: application/jsonBody
{
"authorization_url": "https://www.facebook.com/v2.10/dialog/oauth?0=email&1=public_profile&state=b400ccac0772117cac330a6ff8f72293&scope=public_profile%2Cemail&response_type=code&approval_prompt=auto&redirect_uri=https%3A%2F%2Fwww.spotahome.com&client_id=250342588822106",
"oauth2state": "b400ccac0772117cac330a6ff8f72293"
}Response
422Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request was well formed but was unable to be followed due to semantic errors",
"status": 422,
"title": "Unprocessable Entity",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains a property for each field that failed validation."
}
}
}Authentication DEPRECATEDPOST/authentications/facebook
Authenticates in Facebook API and verifies if the account exists and it is enabled. Returns a pair of JWT token if authenticated successfully: access token and refresh token.
Example URI
POST https://user-identity.spotahome.com/authentications/facebook
Request
Headers
Content-Type: application/jsonBody
{
"code": "fe613f87650b568dbb49e",
"redirect_uri": "http://bff.spotahome.com/facebook/check",
"login_context": "tenant",
"locale": "en"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"code": {
"type": "string"
},
"redirect_uri": {
"type": "string"
},
"login_context": {
"type": "string",
"description": "Can be of types tenant, landlord or employee"
},
"locale": {
"type": "string",
"description": "Identifies the locale of the user that wants to authenticate"
}
},
"required": [
"code",
"redirect_uri",
"login_context",
"locale"
]
}Response
201Headers
Content-Type: application/jsonBody
{
"jwt": "aa.bb.cc",
"accessToken": "aa.bb.cc",
"refreshToken": "dd.ee.ff"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"jwt": {
"type": "string",
"description": "Deprecated field. Use accessToken instead, it has same value."
},
"accessToken": {
"type": "string",
"description": "The access token to use for access to APIs."
},
"refreshToken": {
"type": "string",
"description": "The refresh token to use for request new access tokens"
}
}
}Response
401Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request requires user authentication",
"status": 401,
"title": "Unauthorized",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains the error code and the description"
}
}
}Response
409Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request could not be completed due to a conflict with the current state of the resource",
"status": 409,
"title": "Conflict",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "the error code and the description."
}
}
}Response
422Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request was well formed but was unable to be followed due to semantic errors",
"status": 422,
"title": "Unprocessable Entity",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains a property for each field that failed validation."
}
}
}AuthenticationPOST/oauth/facebook
Authenticates in Facebook API with an access token and verifies if the account exists and it is enabled. Returns a pair of JWT token if authenticated successfully: access token and refresh token.
Example URI
POST https://user-identity.spotahome.com/oauth/facebook
Request
Headers
Content-Type: application/jsonBody
{
"access_token": "fe613f87650b568dbb49e",
"login_context": "tenant",
"locale": "en"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"access_token": {
"type": "string"
},
"login_context": {
"type": "string",
"description": "Can be of types tenant, landlord or employee"
},
"locale": {
"type": "string",
"description": "Identifies the locale of the user that wants to authenticate"
}
},
"required": [
"access_token",
"login_context",
"locale"
]
}Response
201Headers
Content-Type: application/jsonBody
{
"jwt": "aa.bb.cc",
"accessToken": "aa.bb.cc",
"refreshToken": "dd.ee.ff"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"jwt": {
"type": "string",
"description": "Deprecated field. Use accessToken instead, it has same value."
},
"accessToken": {
"type": "string",
"description": "The access token to use for access to APIs."
},
"refreshToken": {
"type": "string",
"description": "The refresh token to use for request new access tokens"
}
}
}Response
401Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request requires user authentication",
"status": 401,
"title": "Unauthorized",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains the error code and the description"
}
}
}Response
409Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request could not be completed due to a conflict with the current state of the resource",
"status": 409,
"title": "Conflict",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "the error code and the description."
}
}
}Response
422Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request was well formed but was unable to be followed due to semantic errors",
"status": 422,
"title": "Unprocessable Entity",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains a property for each field that failed validation."
}
}
}Apple ¶
Authenticates with Apple Oauth
ApplePOST/oauth/apple
Authenticates with Apple an access token and verifies if the account exists and it is enabled. To be precise, we check that the access token provided was issued by Apple, calling their servers, we don’t really authenticate since this is happening in the tenant app side. When sign-up a user, we need to specify the full_name. Returns a pair of JWT token if authenticated successfully: access token and refresh token.
Example URI
POST https://user-identity.spotahome.com/oauth/apple
Request
Headers
Content-Type: application/jsonBody
{
"access_token": "fe613f87650b568dbb49e",
"login_context": "tenant",
"locale": "en",
"full_name": "'Steve Jobs'"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"access_token": {
"type": "string"
},
"login_context": {
"type": "string",
"description": "Can be of types tenant, landlord or employee"
},
"locale": {
"type": "string",
"description": "Identifies the locale of the user that wants to authenticate"
},
"full_name": {
"type": "string",
"description": "User name used when creating the account"
}
},
"required": [
"access_token",
"login_context",
"locale"
]
}Response
200Headers
Content-Type: application/jsonBody
{
"jwt": "aa.bb.cc",
"accessToken": "aa.bb.cc",
"refreshToken": "dd.ee.ff"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"jwt": {
"type": "string",
"description": "Deprecated field. Use accessToken instead, it has same value."
},
"accessToken": {
"type": "string",
"description": "The access token to use for access to APIs."
},
"refreshToken": {
"type": "string",
"description": "The refresh token to use for request new access tokens"
}
}
}Response
401Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request requires user authentication",
"status": 401,
"title": "Unauthorized",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains the error code and the description"
}
}
}Response
409Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request could not be completed due to a conflict with the current state of the resource",
"status": 409,
"title": "Conflict",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "the error code and the description."
}
}
}Response
422Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request was well formed but was unable to be followed due to semantic errors",
"status": 422,
"title": "Unprocessable Entity",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains a property for each field that failed validation."
}
}
}Erasmusu ¶
Erasmusu Auth. Login and signup with access token from Erasmusu Auth service.
ErasmusuPOST/oauth/erasmusu
Authenticates in Erasmusu authentication service with an access token and verifies if the account exists and it is enabled. Returns a pair of JWT token if authenticated successfully: access token and refresh token.
Example URI
POST https://user-identity.spotahome.com/oauth/erasmusu
Request
Headers
Content-Type: application/jsonBody
{
"access_token": "fe613f87650b568dbb49e",
"login_context": "tenant",
"locale": "en"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"access_token": {
"type": "string"
},
"login_context": {
"type": "string",
"description": "Can be of type of tenant"
},
"locale": {
"type": "string",
"description": "Identifies the locale of the user that wants to authenticate"
}
},
"required": [
"access_token",
"login_context",
"locale"
]
}Response
201Headers
Content-Type: application/jsonBody
{
"jwt": "aa.bb.cc",
"accessToken": "aa.bb.cc",
"refreshToken": "dd.ee.ff"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"jwt": {
"type": "string",
"description": "Deprecated field. Use accessToken instead, it has same value."
},
"accessToken": {
"type": "string",
"description": "The access token to use for access to APIs."
},
"refreshToken": {
"type": "string",
"description": "The refresh token to use for request new access tokens"
}
}
}Response
401Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request requires user authentication",
"status": 401,
"title": "Unauthorized",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains the error code and the description"
}
}
}Response
409Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request could not be completed due to a conflict with the current state of the resource",
"status": 409,
"title": "Conflict",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "the error code and the description."
}
}
}Response
422Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request was well formed but was unable to be followed due to semantic errors",
"status": 422,
"title": "Unprocessable Entity",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains a property for each field that failed validation."
}
}
}WGGesucht ¶
WGGesucht Auth. Login and signup with access token from WGGesucht Auth service.
WGGesuchtPOST/oauth/wgg
Authenticates in WGGesucht authentication service with an access token and verifies if the account exists and it is enabled. Returns a pair of JWT token if authenticated successfully: access token and refresh token.
Example URI
POST https://user-identity.spotahome.com/oauth/wgg
Request
Headers
Content-Type: application/jsonBody
{
"access_token": "fe613f87650b568dbb49e",
"login_context": "tenant",
"locale": "en"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"access_token": {
"type": "string"
},
"login_context": {
"type": "string",
"description": "Can be of type of tenant"
},
"locale": {
"type": "string",
"description": "Identifies the locale of the user that wants to authenticate"
}
},
"required": [
"access_token",
"login_context",
"locale"
]
}Response
201Headers
Content-Type: application/jsonBody
{
"jwt": "aa.bb.cc",
"accessToken": "aa.bb.cc",
"refreshToken": "dd.ee.ff"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"jwt": {
"type": "string",
"description": "Deprecated field. Use accessToken instead, it has same value."
},
"accessToken": {
"type": "string",
"description": "The access token to use for access to APIs."
},
"refreshToken": {
"type": "string",
"description": "The refresh token to use for request new access tokens"
}
}
}Response
401Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request requires user authentication",
"status": 401,
"title": "Unauthorized",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains the error code and the description"
}
}
}Response
409Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request could not be completed due to a conflict with the current state of the resource",
"status": 409,
"title": "Conflict",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "the error code and the description."
}
}
}Response
422Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request was well formed but was unable to be followed due to semantic errors",
"status": 422,
"title": "Unprocessable Entity",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains a property for each field that failed validation."
}
}
}Token Info ¶
JWT infoGET/me
Different audiences:
-
access_token: Token with the purpose of access APIs
-
refresh_token: Token with the purpose of request a new access token
Example URI
GET https://user-identity.spotahome.com/me
Request
Headers
Content-Type: application/json
Authorization: aa.bb.ccResponse
200Headers
Content-Type: application/jsonBody
{
"jwt" : {
"header" : {
"typ" : "JWT",
"alg" : "HS512"
},
"payload" : {
"sub": "598b1084-20fc-4df2-b3e6-cd0cf2065848",
"aud": "access_token",
"jti": "fcf3bf9b-b199-48df-bb69-6afa3013bbe3",
"exp" : "1470220576",
"iat" : "1470220533"
"iss" : "spotahome.com",
"user_id": "598b1084-20fc-4df2-b3e6-cd0cf2065848",
"roles" : [
"foo",
"bar"
]
}
}
Response
401Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request requires user authentication",
"status": 401,
"title": "Unauthorized",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains the error code and the description"
}
}
}Refresh access token ¶
Refresh access tokenPOST/authentications/me/refresh
Mandatory: Token used needs to be a refresh token with the audience “refresh_token”
Example URI
POST https://user-identity.spotahome.com/authentications/me/refresh
Request
Headers
Content-Type: application/json
Authorization: aa.bb.ccResponse
201Headers
Content-Type: application/jsonBody
{
"jwt": "aa.bb.cc",
"accessToken": "aa.bb.cc",
"refreshToken": "dd.ee.ff"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"jwt": {
"type": "string",
"description": "Deprecated field. Use accessToken instead, it has same value."
},
"accessToken": {
"type": "string",
"description": "The access token to use for access to APIs."
},
"refreshToken": {
"type": "string",
"description": "The refresh token to use for request new access tokens"
}
}
}Response
401Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request requires user authentication",
"status": 401,
"title": "Unauthorized",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains the error code and the description"
}
}
}Event Store ¶
Event Store ¶
Get EventsGET/event-store/{fromEventId}/{toEventId}{?typeName}
Gets a specific set of domain events from a specific interval. A maximum of 500 results will be shown if more are requested.
Example URI
GET https://user-identity.spotahome.com/event-store/1/100?typeName=SocialUserWasRegistered,UserWasCreated
URI Parameters
- fromEventId
number(required) Example: 1From domain event id
- toEventId
number(required) Example: 100To domain event id
- typeName
array[string](optional) Example: SocialUserWasRegistered,UserWasCreatedEvent typename
Request
Headers
Authorization: aa.bb.ccResponse
200Headers
Content-Type: application/jsonBody
{
"events": [
{
"id": "1",
"type_name": "Sah\\Domain\\User\\UserRoleWasAdded",
"occurred_on": "2017-07-03T11:20:35.000Z",
"event_body": "{\"role\":\"booking-agent\",userId\":\"5b9f90a5-a0e5-4d29-b660-f337fa314748\",\"occurredOn\":\"2017-07-03T11:20:35+0000\"}"
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"events": {
"type": "array"
}
}
}Response
401Headers
Content-Type: application/jsonBody
{
"detail": "The request requires user authentication",
"status": 401,
"title": "Unauthorized",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains the error code and the description"
}
}
}Profiles ¶
Profiles ¶
Get ProfileGET/profiles/me
Returns the profile for the current user, identified by the authentication token.
A user can only read its own profile.
Example URI
GET https://user-identity.spotahome.com/profiles/me
Request
Headers
Authorization: aa.bb.ccResponse
200Headers
Content-Type: application/jsonBody
{
"phone": "123456789",
"birthday": "2000-12-31",
"gender": "female",
"occupationType": "professional",
"occupationOrganization": "Company Name",
"occupationDescription": "Software engineer",
"country": "spain",
"isCouple": true,
"aboutMe": "More info about me",
"solvency": "family_support",
"salaryFrom": 10,
"salaryTo": 100,
"salaryCurrency": "GBP",
"salaryType": "monthly",
"contacts": [
{
"firstName": "John",
"lastName": "Doe",
"email": "johndoe@test.com",
"phone": "123456789",
"types": "cohabitant"
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"phone": {
"type": "string"
},
"birthday": {
"type": "string",
"description": "Birth date (format YYYY-MM-DD)"
},
"gender": {
"type": "string",
"enum": [
"female",
"male"
]
},
"occupationType": {
"type": "string",
"enum": [
"professional",
"student"
]
},
"occupationOrganization": {
"type": "string"
},
"occupationDescription": {
"type": "string",
"description": "What they do/study"
},
"country": {
"type": "string"
},
"isCouple": {
"type": "boolean"
},
"aboutMe": {
"type": "string"
},
"solvency": {
"type": "string",
"enum": [
"family_support",
"savings",
"scholarship",
"work"
],
"description": "Where the funds are coming from"
},
"salaryFrom": {
"type": "number",
"description": "Salary range from"
},
"salaryTo": {
"type": "number",
"description": "Salary range to"
},
"salaryCurrency": {
"type": "string",
"description": "Currency ISO_4217"
},
"salaryType": {
"type": "string",
"enum": [
"monthly"
],
"description": "Salary type"
},
"contacts": {
"type": "array"
}
}
}Response
401Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request requires user authentication",
"status": 401,
"title": "Unauthorized",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains the error code and the description"
}
}
}Response
404Headers
Content-Type: application/problem+jsonBody
{
"detail": "Resource not found",
"status": 404,
"title": "Not found",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
}
}
}Create OR Update a ProfilePUT/profiles/me
Create a profile, if it doesn’t exist already, or update an existing profile.
The profile is for the current user, identified by the authentication token.
If the user doesn’t have a profile already, a new one will be created.
If the user already has a profile, it will be updated.
- The following attributes will not be updated if they are NULL or non existing in the payload
- occupationDescription
- solvency
- salaryFrom
- salaryTo
- salaryCurrency
- salaryType
- address: { fullAddress, streetName, streetNumber, addressDetails, postalCode, cityId, countryCode, }
A user can only update its own profile.
Example URI
PUT https://user-identity.spotahome.com/profiles/me
Request
Headers
Content-Type: application/json
Authorization: aa.bb.ccBody
{
"phone": "123456789",
"birthday": "2000-12-31",
"gender": "female",
"occupationType": "professional",
"occupationOrganization": "Company Name",
"occupationDescription": "Software engineer",
"country": "spain",
"isCouple": true,
"aboutMe": "More info about me",
"solvency": "family_support",
"salaryFrom": 10,
"salaryTo": 100,
"salaryCurrency": "GBP",
"salaryType": "monthly",
"contacts": [
{
"firstName": "John",
"lastName": "Doe",
"email": "johndoe@test.com",
"phone": "123456789",
"types": "cohabitant"
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"phone": {
"type": "string"
},
"birthday": {
"type": "string",
"description": "Birth date (format YYYY-MM-DD)"
},
"gender": {
"type": "string",
"enum": [
"female",
"male"
]
},
"occupationType": {
"type": "string",
"enum": [
"professional",
"student"
]
},
"occupationOrganization": {
"type": "string"
},
"occupationDescription": {
"type": "string",
"description": "What they do/study"
},
"country": {
"type": "string"
},
"isCouple": {
"type": "boolean"
},
"aboutMe": {
"type": "string"
},
"solvency": {
"type": "string",
"enum": [
"family_support",
"savings",
"scholarship",
"work"
],
"description": "Where the funds are coming from"
},
"salaryFrom": {
"type": "number",
"description": "Salary range from"
},
"salaryTo": {
"type": "number",
"description": "Salary range to"
},
"salaryCurrency": {
"type": "string",
"description": "Currency ISO_4217"
},
"salaryType": {
"type": "string",
"enum": [
"monthly"
],
"description": "Salary type"
},
"contacts": {
"type": "array"
}
}
}Response
204Headers
Location: /profiles/meResponse
401Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request requires user authentication",
"status": 401,
"title": "Unauthorized",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains the error code and the description"
}
}
}Response
422Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request was well formed but was unable to be followed due to semantic errors",
"status": 422,
"title": "Unprocessable Entity",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains a property for each field that failed validation."
}
}
}Profiles by ID ¶
Get Profile by IDGET/profiles/{id}
Get profile by id.
Authorization: protected for uai_admin and uai_employee roles.
Example URI
GET https://user-identity.spotahome.com/profiles/68a5sdf67
URI Parameters
- id
string(required) Example: 68a5sdf67The user ID
Request
Headers
Authorization: aa.bb.ccResponse
200Headers
Content-Type: application/jsonBody
{
"phone": "123456789",
"birthday": "2000-12-31",
"gender": "female",
"occupationType": "professional",
"occupationOrganization": "Company Name",
"occupationDescription": "Software engineer",
"country": "spain",
"isCouple": true,
"aboutMe": "More info about me",
"solvency": "family_support",
"salaryFrom": 10,
"salaryTo": 100,
"salaryCurrency": "GBP",
"salaryType": "monthly",
"contacts": [
{
"firstName": "John",
"lastName": "Doe",
"email": "johndoe@test.com",
"phone": "123456789",
"types": "cohabitant"
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"phone": {
"type": "string"
},
"birthday": {
"type": "string",
"description": "Birth date (format YYYY-MM-DD)"
},
"gender": {
"type": "string",
"enum": [
"female",
"male"
]
},
"occupationType": {
"type": "string",
"enum": [
"professional",
"student"
]
},
"occupationOrganization": {
"type": "string"
},
"occupationDescription": {
"type": "string",
"description": "What they do/study"
},
"country": {
"type": "string"
},
"isCouple": {
"type": "boolean"
},
"aboutMe": {
"type": "string"
},
"solvency": {
"type": "string",
"enum": [
"family_support",
"savings",
"scholarship",
"work"
],
"description": "Where the funds are coming from"
},
"salaryFrom": {
"type": "number",
"description": "Salary range from"
},
"salaryTo": {
"type": "number",
"description": "Salary range to"
},
"salaryCurrency": {
"type": "string",
"description": "Currency ISO_4217"
},
"salaryType": {
"type": "string",
"enum": [
"monthly"
],
"description": "Salary type"
},
"contacts": {
"type": "array"
}
}
}Response
401Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request requires user authentication",
"status": 401,
"title": "Unauthorized",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains the error code and the description"
}
}
}Response
404Headers
Content-Type: application/problem+jsonBody
{
"detail": "Resource not found",
"status": 404,
"title": "Not found",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
}
}
}Documents ¶
Generate an upload url ¶
Generate an upload urlPOST/me/documents/upload-url
Returns a signed url which allows to make a PUT request to upload a file directly to S3.
Example URI
POST https://user-identity.spotahome.com/me/documents/upload-url
Request
Headers
Content-Type: application/json
Authorization: aa.bb.ccBody
{
"filetype": "image/png"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"filetype": {
"type": "string"
}
}
}Response
200Headers
Content-Type: application/jsonBody
{
"signedUploadUrl": "https://bucket-name.s3....com/abcde/fghij",
"filePath": "abcde/fghij"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"signedUploadUrl": {
"type": "string"
},
"filePath": {
"type": "string"
}
}
}Response
401Headers
Content-Type: application/jsonBody
{
"detail": "The request requires user authentication",
"status": 401,
"title": "Unauthorized",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains the error code and the description"
}
}
}Save uploaded document ¶
Save uploaded documentPOST/me/documents
Saves the given document filepath as owned by a given user.
Example URI
POST https://user-identity.spotahome.com/me/documents
Request
Headers
Content-Type: application/json
Authorization: aa.bb.ccBody
{
"filePath": "'abcde/fghi'",
"documentType": "id_front"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"filePath": {
"type": "string"
},
"documentType": {
"type": "string",
"enum": [
"id_front",
"id_back",
"proof_of_income",
"proof_of_income_additional"
]
}
}
}Response
201Headers
Content-Type: application/jsonBody
{}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {}
}Response
401Headers
Content-Type: application/jsonBody
{
"detail": "The request requires user authentication",
"status": 401,
"title": "Unauthorized",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains the error code and the description"
}
}
}Document download url ¶
Document download urlGET/documents/{documentId}/download?expires={expires}
Gets the S3 signed url to download a document.
This endpoint requires and “uai_admin” or a “uai_tenant_document_manager” jwt token.
Example URI
GET https://user-identity.spotahome.com/documents/abcdefg/download?expires=120
URI Parameters
- documentId
string(required) Example: abcdefgThe uuid of the document.
- expires
integer(optional) Example: 120Number of seconds the link will be valid.
Request
Headers
Content-Type: application/json
Authorization: aa.bb.ccResponse
200Body
{
"signedDownloadUrl": "https://bucket-name.s3....com/abcde/fghij"
}Schema
{
"type": "object",
"properties": {
"signedDownloadUrl": {
"type": "string"
}
},
"$schema": "http://json-schema.org/draft-04/schema#"
}Response
404Headers
Content-Type: application/jsonBody
{
"detail": "Resource not found",
"status": 404,
"title": "Not found",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
}
}
}Document download url by path ¶
Document download url by pathGET/documents/{userId}/{filename}/download-url?expires={expires}
Gets the S3 signed url to download a document.
This endpoint requires and “uai_admin” or a “uai_tenant_document_manager” jwt token.
Example URI
GET https://user-identity.spotahome.com/documents/abcdefg/abcdefg/download-url?expires=120
URI Parameters
- userId
string(required) Example: abcdefgThe uuid of the user owner of the document.
- filename
string(required) Example: abcdefgThe filename of the document.
- expires
integer(optional) Example: 120Number of seconds the link will be valid.
Request
Headers
Content-Type: application/json
Authorization: aa.bb.ccResponse
200Body
{
"signedDownloadUrl": "https://bucket-name.s3....com/abcde/fghij"
}Schema
{
"type": "object",
"properties": {
"signedDownloadUrl": {
"type": "string"
}
},
"$schema": "http://json-schema.org/draft-04/schema#"
}Response
404Headers
Content-Type: application/jsonBody
{
"detail": "Resource not found",
"status": 404,
"title": "Not found",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
}
}
}Delete a document ¶
Delete a documentDELETE/documents/{documentId}
Unlink a document from a user. This doesn’t delete the file from S3.
Example URI
DELETE https://user-identity.spotahome.com/documents/abcdefg
URI Parameters
- documentId
string(required) Example: abcdefgThe uuid of the document.
Request
Headers
Content-Type: application/json
Authorization: aa.bb.ccResponse
204Response
404Headers
Content-Type: application/jsonBody
{
"detail": "Resource not found",
"status": 404,
"title": "Not found",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
}
}
}Response
401Headers
Content-Type: application/jsonBody
{
"detail": "The request requires user authentication",
"status": 401,
"title": "Unauthorized",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains the error code and the description"
}
}
}Get documents from a user ¶
Get documents from a userGET/{userId}/documents
Get all documents from a user.
This endpoint requires and “uai_admin” or a “uai_tenant_document_manager” jwt token.
Example URI
GET https://user-identity.spotahome.com/68a5sdf67/documents
URI Parameters
- userId
string(required) Example: 68a5sdf67The user ID
Request
Headers
Content-Type: application/jsonResponse
200Headers
Content-Type: application/jsonBody
{
"count": 2,
"total": 2,
"_links": {
"self": {
"href": "/64d5234f-4b9a-4b8b-bc74-d5eb8340af5f/documents?page=1"
},
"first": {
"href": "/64d5234f-4b9a-4b8b-bc74-d5eb8340af5f/documents?page=1"
},
"last": {
"href": "/64d5234f-4b9a-4b8b-bc74-d5eb8340af5f/documents?page=1"
}
},
"_embedded": {
"documents": [
{
"id": "aaaaa-bbbb-cccc",
"userId": "aaaaa-bbbb-cccc",
"filePath": "64d5234f-4b9a-4b8b-bc74-d5eb8340af5f/6765d4e9-4a8c-43c5-a7a9-4be8e54e6efc",
"uploadedAt": "2022-09-07 11:57:15",
"documentType": "id_back"
}
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"count": {
"type": "number"
},
"total": {
"type": "number"
},
"_links": {
"type": "object",
"properties": {
"self": {
"type": "object",
"properties": {
"href": {
"type": "string"
}
},
"required": [
"href"
]
},
"first": {
"type": "object",
"properties": {
"href": {
"type": "string"
}
},
"required": [
"href"
]
},
"last": {
"type": "object",
"properties": {
"href": {
"type": "string"
}
},
"required": [
"href"
]
}
},
"required": [
"self",
"first",
"last"
]
},
"_embedded": {
"type": "object",
"properties": {
"documents": {
"type": "array"
}
}
}
},
"required": [
"count",
"total",
"_links"
]
}List document types ¶
List document typesGET/documents/types
Example URI
GET https://user-identity.spotahome.com/documents/types
Request
Headers
Content-Type: application/jsonResponse
200Body
[
"id_front",
"id_back",
"proof_of_income",
"proof_of_income_additional",
"proof_of_occupation"
]Schema
{
"type": "array",
"items": {
"type": "string"
},
"$schema": "http://json-schema.org/draft-04/schema#"
}Phone verification ¶
Phone verification ¶
Request phone verificationPOST/phone-verifications
Request a verification code to be sent to the user.
Events triggered
- PhoneVerificationWasCreated
Example URI
POST https://user-identity.spotahome.com/phone-verifications
Request
Headers
Authorization: aa.bb.ccBody
{
"phone": "+447123456789",
"channel": "sms",
"locale": "en"
}Schema
{
"type": "object",
"properties": {
"phone": {
"type": "string"
},
"channel": {
"enum": [
"sms",
"call"
]
},
"locale": {
"enum": [
"en",
"es",
"it",
"pt"
]
}
},
"$schema": "http://json-schema.org/draft-04/schema#"
}Response
201Headers
Content-Type: application/jsonBody
{
"id": "VE453d6d20ab80da21",
"phone": "+447123456789",
"channel": "sms",
"status": "pending"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "string"
},
"phone": {
"type": "string"
},
"channel": {
"type": "string",
"enum": [
"sms",
"call"
]
},
"status": {
"type": "string"
}
}
}Response
401Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request requires user authentication",
"status": 401,
"title": "Unauthorized",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains the error code and the description"
}
}
}Response
422Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request was well formed but was unable to be followed due to semantic errors",
"status": 422,
"title": "Unprocessable Entity",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains a property for each field that failed validation."
}
}
}Phone verification check ¶
Phone verification checkPOST/phone-verifications/check
Check whether the code is correct against a pending verification request. If code is correct, updates the state to approved.
Events triggered
- PhoneVerificationWasApproved
- PhoneVerificationWasInvalid
Example URI
POST https://user-identity.spotahome.com/phone-verifications/check
Request
Headers
Authorization: aa.bb.ccBody
{
"phone": "+447123456789",
"code": "123456"
}Schema
{
"type": "object",
"properties": {
"phone": {
"type": "string"
},
"code": {
"type": "string"
}
},
"$schema": "http://json-schema.org/draft-04/schema#"
}Response
200Headers
Content-Type: application/jsonBody
{
"id": "VE453d6d20ab80da21",
"phone": "+447123456789",
"channel": "sms",
"status": "pending",
"valid": true
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "string"
},
"phone": {
"type": "string"
},
"channel": {
"type": "string",
"enum": [
"sms",
"call"
]
},
"status": {
"type": "string",
"enum": [
"pending",
"approved"
]
},
"valid": {
"type": "boolean"
}
}
}Response
401Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request requires user authentication",
"status": 401,
"title": "Unauthorized",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains the error code and the description"
}
}
}Response
404Pending phone verification not found.
Headers
Content-Type: application/problem+jsonBody
{
"detail": "Resource not found",
"status": 404,
"title": "Not found",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
}
}
}Response
422Headers
Content-Type: application/problem+jsonBody
{
"detail": "The request was well formed but was unable to be followed due to semantic errors",
"status": 422,
"title": "Unprocessable Entity",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616",
"validationMessages": {
"field": {
"stringLength": "The input is less than 6 characters long"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detail": {
"type": "string"
},
"status": {
"type": "number"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"description": "sec10.html (string)"
},
"validationMessages": {
"type": "object",
"properties": {
"field": {
"type": "object",
"properties": {
"stringLength": {
"type": "string"
}
}
}
},
"description": "Contains a property for each field that failed validation."
}
}
}