To use the emnify REST API, you need to authenticate with an authentication token. emnify uses JSON Web Tokens (JWTs) as the authentication token.
There are two ways to retrieve this token:
- Authenticate with user credentials: Use the username and password you provided while signing up for the emnify Portal. This information is available in your User Settings.
- Authenticate with an application token: You can use the application token generated in your emnify account.
Authenticate with user credentials
/api/v1/authenticate API is used to generate a JWT
auth_token, which authenticates subsequent API calls.
The request body must provide a
username (typically the email address used when signing up) and the
Once authenticated, you'll receive an
If you signed up using the emnify Portal, you'll need to enter the password as a SHA-1 hashed string.
The SHA-1 of a password can be generated online or in the terminal via the following command:
echo -n 'my_password' | openssl sha1
To authenticate all API calls, you can use this
auth_token as the bearer token.
auth_token is valid for 240 minutes, so you don’t need to retrieve the
auth_token before every API call.
auth_token expires, you can use the
refresh_token to retrieve the new
Authenticate with an application token
Since you shouldn't store your emnify user credentials on your application server, you can generate an
application_token via the emnify Portal or the API:
The request body should have a description of the token normally used to indicate who is using the token and can have an
expiry_date for the token.
Authorization: Bearer AUTH_TOKEN
"description": "Token with expiry date",
This call returns an
You can use this token instead of the username and password combination.
The token can be revoked at any time.
You can alternatively generate the
application_token in the emnify Portal:
- Log in to the emnify Portal
- On the Integrations page, navigate to the Application Tokens section, and select Add Token.
To get the
auth_token using the
application_token, use the
auth_token can then be used to authenticate all subsequent API calls.
Unlike username and password authentication, the server returns only
refresh_token is included in the response.
auth_token is valid for 240 minutes.
It's not advisable to generate an
auth_token before making each API call.
You should reuse the generated
auth_token for 240 minutes after it's generated.
Then, update it after its expiration.