Topic updated on September 17, 2021

IoT Portal Authentication

The client must authenticate first before sending commands to the IoT Portal. There are two ways to authenticate, as a user or as an application. Both users and applications have security roles assigned, however, an application authenticates with a token that is re-used with other devices, whereas a user is assumed to represent a single individual.

User Authentication
  • A user authenticates with a username (email address) and a password.
  • If multi-factor authentication is enabled for the user and the username and password were correct, an error with error code -90041 is returned. A second authentication request must be sent with an MFA code as the secondary password. The secondary password is a six-digit authentication code that is compatible with the time-based one-time password (TOTP) standard. It is given to the user at the time the user enabled MFA. For more information on MFA, see Multi-Factor Authentication.
  • A user can use the session.org.switch API to switch organizations (if you have access to more than one organization).
  • A user cannot bind Things to its session.
  • Every 5 failed logins incur a 5-minute additive lockout period up to a maximum lockout period of 30 minutes. A user will not be able to login during a lockout period.
Application Authentication
  • An application or client authenticates with IoT Portal using a Thing key, application ID, and an application token.
  • The Thing key is the unique key that associates the application or client to a particular Thing in the M2M Application Platform.
  • The application ID is a unique value that is generated by the device and kept secret. It is associated with the Thing key the first time a device connects and prevents "spoofing" of connections. A good practice is to generate an application ID the first time a device connects and store the value in non-volatile memory so it can be re-used. Using a different application ID for that device will prevent an application from connecting.
  • The application token is supplied via the Management Portal and is an ASCII string that is provided and used by a client as a means to authenticate the session to IoT Portal.  It should be noted that an application token can be reused by many clients, however, each client will be assigned to a Thing object in the platform. 
JWT Authentication
  • A user or application session with Organization Admin rights can generate a JWT token using the "session.jwt.create" API call.
  • JWT tokens are created with a defined role to use to limit access to various API functions.
  • JWT tokens can restrict access to specific Things.
  • JWT tokens have a variable time to live, with a maximum of 1 day.

For protocol-specific authentications, see MQTTAuthentication and HTTPAuthentication.