Auth API

The Auth API is used to authenticate users and let new users sign up.

CONFIRM_SIGN_UP

Required role: None
Required privilege: None

API Endpoint: [POST]: /auth/confirm-sign-up

Confirms the account of a signed up user. This action should be called after a user have received their confirmation e-mail or SMS from the SIGN_UP action to confirm the account. An email will receive a token and an SMS will receive the username and a confirmation code. This endpoint supports confirming the account with either token or username/code.

Request

Headers

  • x-api-key: The API Key to identify the request

Body

  • token: The token that the user received in the confirmation e-mail. The token is sent as a parameter in the url and the client must extract this parameter and send it as-is to this action. required (either token or userName + code is enough)
  • userName: The username that the user chose at signup. required (either token or userName + code is enough)
  • code: The confirmation code that was received in the SMS. required (either token or userName + code is enough)

Example payload

{
  "token": "eyJ1c2VyTmFtZSI6ImpvYWtpbSIsInRpbWVzdGFtcCI6MTUwNjMxNDI4MzcxOH0=-312409"
}

OR

{
  "userName": "Demo",
  "code": "123456"
}
Key Params Property Description
PROPERTY_REQUIRED token Returned if no token was provided.
INVALID_LOGIN token Returned if the token is incorrect or has expired.
USER_NOT_FOUND token Returned if the user cannot be found.

FORGOT_PASSWORD

Required role: None
Required privilege: None

API Endpoint: [POST]: /auth/forgot-password

If a user has forgotten the account password, this action can be used to let them reset their password. The user will get an email message containing a link to set a new password. The link is usable only once. Note: After having invoked this action, it is still possible to login using the correct credentials; the password is not changed until the user has responded to the email sent by the FORGOT_PASSWORD action.

For security reasons, if an invalid userName is provided in the request, no error message will be returned.

Request

Headers

  • x-api-key: The API Key to identify the request

Body

  • userName: The user name of the user to request a password reset link for. required

Example payload

{
  "userName": "demo"
}
Key Params Property Description
PROPERTY_REQUIRED userName Returned if no user name was provided.

Required role: None
Required privilege: None

API Endpoint: [GET]: /auth/get-consent-document

Get a signed url to the latest version of a consent document (terms of service).

Request

Headers

  • x-api-key: The API Key to identify the request

Response

  • url: The URL to use to get the file. This will give you temporary access to the file.
  • version: The custom version of the file.

Errors

Key Params Property Description
FILE_NOT_FOUND Returned if the consent document cannot be found.

LOGIN

Required role: None
Required privilege: None

API Endpoint: [POST]: /auth/login

Checks if a user is authorized to login and returns credentials that should be used when communicating with AWS. The access token is valid for 60 minutes, whereafter it needs to be refreshed.

Request

Headers

  • x-api-key: The API Key to identify the request

Body

  • userName: The user name of the user. required
  • password: The password of the user. required

Example payload

{
  "userName": "demo",
  "password": "Demo1234"
}

Response

  • user
    • userName: The user name of the user.
    • roleName: The name of the role that the user has ( Read | ReadWrite ).
    • firstName: The first name of the user.
    • lastName: The last name of the user.
    • email: The e-mail address of the user.
  • credentials
    • identityId: A Cognito IdentityId to use when communicating with AWS.
    • token: A OpenID Connect token to use when communicating with AWS.
    • refreshToken: A refresh token to use for getting a new access token.
  • permissions
    • objects: A list of privilege objects with allowed operations for the user’s role, i.e. CREATE, READ, UPDATE or DELETE.

Errors

Key Params Property Description
PROPERTY_REQUIRED userName Returned if no user name was provided.
PROPERTY_REQUIRED password Returned if no password was provided.
INVALID_LOGIN Returned if the user name or password was incorrect.

Required role: None
Required privilege: None

You may require users to consent to terms and conditions before they can use the service. Use this endpoint to register that a user has given their consent.

API Endpoint: [POST]: /auth/consent

Request

Headers

  • x-api-key: The API Key to identify the request

Body

  • userName: The user name of the user. required
  • password: The password of the user. required

Example payload

{
  "userName": "demo",
  "password": "Demo1234"
}

Response

An empty object.

Errors

Key Params Property Description
PROPERTY_REQUIRED userName Returned if no user name was provided.
PROPERTY_REQUIRED password Returned if no password was provided.
INVALID_LOGIN Returned if the user name or password was incorrect.

REFRESH

Required role: None
Required privilege: None

API Endpoint: [POST]: /auth/refresh

Lets a user refresh the token. Use the refreshToken acquired from the LOGIN call described above. By default, the refresh token is set to expire after 30 days but this can be changed to an arbitrary period.

To use the refresh token to get a new set of tokens, do the same call as you did when you logged in but use the refresh action instead and pass the refresh token as the argument. Please note that you need to reset your logins before you do this, otherwise you will try to do an authenticated call and since the access token is no longer valid, this will fail.

The response from refresh is exactly the same as from the login request, and should be handled the same way. In Managed IoT Cloud App Board the refresh token is implemented by checking for errors and if the token has expired, it is refreshed and the operation is retried, and if it still fails, the user is redirected to the login page.

Request

Headers

  • x-api-key: The API Key to identify the request

Body

  • refreshToken: The refresh token acquired when logging in. required

Example payload

{
  "refreshToken": "eyJjdHkiOiJKV1QiLCJlbmMiOi..."
}

Response

  • user
    • userName: The user name of the user.
    • roleName: The name of the role that the user has ( Read | ReadWrite ).
    • firstName: The first name of the user.
    • lastName: The last name of the user.
    • email: The e-mail address of the user.
  • credentials
    • identityId: A Cognito IdentityId to use when communicating with AWS.
    • token: A OpenID Connect token to use when communicating with AWS.
    • refreshToken: A refresh token to use for getting a new access token.
  • permissions
    • objects: A list of privilege objects with allowed operations for the user’s role, i.e. CREATE, READ, UPDATE or DELETE.

Errors

Key Params Property Description
PROPERTY_REQUIRED refreshToken Returned if no refresh token was provided.
INVALID_LOGIN Returned if the refresh token was incorrect.

RESEND_CONFIRMATION_CODE

Required role: None
Required privilege: None

API Endpoint: [POST]: /auth/resend-confirmation-code

Sends a new confirmation code to the user if the user didn’t receive an e-mail or if the link has expired.

Request

Headers

  • x-api-key: The API Key to identify the request

Body

  • userName: The user name of the user to resend the confirmation code for. required

Example payload

{
  "userName": "demo"
}

SET_PASSWORD

Required role: None
Required privilege: None

[POST]: /auth/set-password

Sets the password of the user based on a token sent by the system when the user either forgets their password or is just created by an administrator.

Request

Headers

  • x-api-key: The API Key to identify the request

Body

  • token:The token that the user received in the confirmation e-mail. The token is sent as a parameter in the url and the application must extract this parameter and send it as-is to this action. required (either token or userName + code is enough)
  • userName: The username that the user chose at signup. required (either token or userName + code is enough)
  • code: The confirmation code that was received in the SMS. required (either token or userName + code is enough)
  • password : The new password for the user. Must follow the regex /(?=.[A-Z])(?=.[a-z])(?=.*\d).{8,}/. required (There are at least 8 characters, one digit, one upper case and one lower case letter)
Key Params Property Description
PROPERTY_REQUIRED token Returned if no token was provided.
PROPERTY_REQUIRED password Returned if no password was provided.
INVALID_LOGIN token Returned if the token is incorrect or has expired.
USER_NOT_FOUND token Returned if the user contained in the token doesn’t exist.

SIGN_UP

Required role: None
Required privilege: None

API Endpoint: [POST]: /auth/sign-up

Lets a user initiate the process to create a Managed IoT Cloud user account. A successful sign up will result in an email containing a link being sent to their provided email address. Following that link verifies their email address. If a user didn’t get that email or if the link has expired, there is a possibility to resend the email via the endpoint /auth/resend-confirmation-code.

Request

Headers

  • x-api-key: The API Key to identify the request

Body

  • userName: The user name of the user. Maximum length: 128 characters. required
  • password: The password of the user. required
  • email: The email address of the user. required
  • firstName: First name of the user.
  • lastName: Last name of the user.
  • locale: The locale of the user. This is an ISO639‑1 language code in lowercase and an ISO3166‑1 country code in uppercase, separated by a dash. For example, en-US or sv-SE. When not specified, it will default to en-US.
  • phone: User’s phone number, needs to start with a country code (eg. +46) and cannot contain any whitespace or delimiters.
  • company: User’s company.
  • address: Address of the user.
  • zip: Zip code of the user’s address.
  • city: City of the user’s address.
  • country: Country of the user’s address.
  • consent: If the user has to give consent to terms and conditions before signing up, they need to set this boolean to true. required if the account requires consent, otherwise optional . Refer to the GIVE_CONSENT endpoint for more details.
  • notes1: Additional notes field.
  • notes2: Additional notes field.
  • notes3: Additional notes field.

Example payload

{
  "userName": "demo",
  "password": "demo",
  "email": "email@example.com"
}

Response

  • userName: The username for the user.
  • UserConfirmed: A boolean which indicates the user registration has been conformed or not.
  • UserSub: The id of the user.
  • CodeDeliveryDetails
    • AttributeName: Is always “email”.
    • DeliveryMedium: Is always “EMAIL”.
    • Destination: The email of the user.

UserConfirmed, UserSub and CodeDeliveryDetails of the response are deprecated.

Errors

Key Params Property Description
PROPERTY_REQUIRED userName Returned if no user name was provided.
PROPERTY_REQUIRED password Returned if no password was provided.
PROPERTY_REQUIRED email Returned if no email address was provided.
USER_USERNAME_EXISTS userName Returned if the user name that was provided is used by another user in the system.
USER_CONSENT_REQUIRED consent Returned if consent is required, and the user did not give it.