Authentication

With the exception of a few endpoints, users must use token-based authentication on every API call. Authentication must be provided with a user token using the Basic Auth scheme, detailed below. The steps for resetting passwords are also detailed on this page.

Basic Token Authentication

A permanent API token is generated when a user's profile is created. This token can be found in the POST response's body in the api_token field. If you're creating profiles for your customers, give them this token. If they need to reset their token, they can do so via the api_token_reset route, outlined below.

URL:

POST https://api.edgeiq.io/api/v1/platform/user/api_token_reset

Headers:

Accept: application/json
Content-Type: application/json

Body:

{
  "email": "[email protected]",
  "password": "theirpassword"
}

Their permanent API token will be found in the api_token field of the response body.

Generating a temporary API token can be done via the user/authenticate route. The token_expiry field is optional; if omitted the token will expire in 4 hours. The value of token_expiry must be a UTC datetime no greater than a week in the future.

URL:

POST https://api.edgeiq.io/api/v1/platform/user/authenticate

Headers:

Accept: application/json
Content-Type: application/json

Body:

{
  "email": "[email protected]",
  "password": "yourpassword",
  "token_expiry": "2019-06-10T19:49:51.217Z"
}

This request will return the JSON representation of that user. Included in that response body is the session_token field and the token's expiration date in the session_expires_at field. Users can use this token to make subsequent calls.

Now that you have your API token you can issue requests that use that token. The Authorization header's value must be that token.

Authorization: [your token]

You can test to see that your token is working by issuing a request to get your user via the /me route, outlined below.

URL:

GET https://api.edgeiq.io/api/v1/platform/me

Headers:

Accept: application/json
Content-Type: application/json
Authorization: <your token>

The response, if successful, will have a status of 200 OK and will provide a response body that contains your user profile information. You will know that your token is incorrect if the status returned is 403 Forbidden with a response of Not Authorized. Go back to the authentication steps outlined above to ensure you generated your API token correctly.

Resetting Passwords via the API

Resetting Your Password
The password reset process is composed of two steps: sending a request to prompt for a password reset email, and following the link in the received email to reset one's password.

The request outlined below will send a password reset email to the email address in the request body. If the email address included in the body does not belong to a user profile, the request will fail and will return a 404 Status. The url field should always be the value shown below. It is used by our underlying systems to differentiate between deployment environments.

URL:

POST https://api.edgeiq.io/api/v1/platform/user/password_reset_request

Headers:

Accept: application/json
Content-Type: application/json

Body:

{
  "email": "[email protected]",
  "url": "https://app.edgeiq.io/reset_password"
}

A successful request will prompt for an email to be sent to the entered email address. That email will be from [email protected]. Never follow links in emails from email addresses you do not recognize. Follow the link in the email to reset your password. Alternatively, if you take the token query value from the link in the email, you can send the request outlined below to reset your password. After a certain amount of time, the email and token will expire. If your token has expired or if the passwords do not match the request will fail. Return to the step above in order to prompt for a new email, and thereby a new token.

URL:

POST https://api.edgeiq.io/api/v1/platform/user/password_reset/<TOKEN>

Headers:

Accept: application/json
Content-Type: application/json

Body:

{
  "password": "yournewpassword",
  "password_confirmation": "yournewpassword",
}

Customizing The Password Reset Email

For those developing applications on the EdgeIQ API, there are some customization options available for the password reset email. The following body contains the required fields, email and url plus the optional customization fields, which you may mix and match at your discretion. (Note the restriction on customizing the from_address below):

Body:

{
  "email": "[email protected]",
  "url": "https://app.edgeiq.io/reset_password",
  "subject": "Your Recent Password Reset Request",
  "greeting": "We've received a password reset request",
  "from_address": "[email protected]"
}

Note, that in order to customize the from_address field, you MUST contact our support so that we can whitelist the email address. Until this procedure is complete, password reset requests using a customized from_address will cause a 500 to be returned from the API.

Resetting Passwords Via the EdgeIQ Portal

If You've Forgotten Your Password
Visit the Login page of the EdgeIQ Portal. Below the password field is a "Forgot your password?" link to begin the password reset process. Enter your email address in the modal that appears and click the submit button. If the email address does not belong to an existing profile, a message will appear saying so. An email will be sent to the entered address containing a link that will take you to a page to reset your password. Return to the Login page to sign in with your new credentials after you've changed your password.

If You're Still Logged In
If you are still logged into the EdgeIQ Portal you can change your password by clicking the profile image in the top right of the window. Select the "Manage My Profile" option from the dropdown. A modal will then appear, allowing you to edit your profile's details and also your password.

Changing Profiles You Manage
In order to set the password of a user profile that you manage, visit the Users page in the EdgeIQ Portal. If you're redirected to the Hub page, your profile's role does not allow you to edit users.