Getting credentials and tokens to use the API

Our security policies require that you have different sets of credentials to access different parts of the ThingSpace Platform and APIs, as explained on this page.

ThingSpace Platform Credentials and Tokens

You need an API Token to send API requests through the ThingSpace Platform. If you haven’t registered or signed in, you won’t have access to a token to use in your application or on API Console pages. You must register and sign in to be able to get keys and generate tokens to work with real devices in your Verizon account.

Obtaining a ThingSpace Token Programmatically

Your application must send an API token in the header of every API request. We use the OAuth2 “client credentials” grant type, and we require that the application key and secret are Base64 encoded. To obtain an API token:

  1. Sign in to staging.thingspace.verizon.com.
  2. On the home page, click My Keys. (Or from any page in the site, click your email address in the top right corner, click “Edit Account,” and then click “Key Management” to go to your keys page.)
  3. Copy the key and the secret and store them in a secure place for your application to use.
  4. Concatenate the key and the secret, with a colon between them, like this:
    my_key_value<strong>:</strong>my_secret_value
  5. Encode the entire string in Base64 format. (To learn more about encoding in Base64 format, visit https://www.base64encode.org/.)
  6. Send a POST request to https://staging.thingspace.verizon.com/api/ts/v1/oauth2/token with the encoded string in the header.
    Curl Example:
    curl -X POST -d "grant_type=client_credentials" -H "Authorization: Basic BASE64_ENCODED_APP_KEY_AND_SECRET" -H "Content-Type: application/x-www-form-urlencoded" "https://staging.thingspace.verizon.com/api/ts/v1/oauth2/token"

The response will contain a token that you must include in the header of all Device Location API requests. The token will be valid for one hour from when it was first issued, and any further token requests during that hour will return the same token.

You can revoke a token with this request format (user your token in place of TokenToRevoke), and then the next token request will return a new token:

curl -i -X POST -H "Authorization: Basic BASE64_ENCODED_APP_KEY_AND_SECRET" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=client_credentials&token=TokenToRevoke" "https://staging.thingspace.verizon.com/api/ts/v1/oauth2/revoke"

The response contains the revoked token in the header; there is no response body.

UWS Login Credentials

The Device Location API requires a special set of credentials that are associated with one or more Verizon business accounts and allow you to manage M2M devices through an API. These credentials are sometimes called “UWS credentials” or a “UWS account.”

  • If you don’t have a Verizon Enterprise account, you can request a trial account when you are ready to test device location services with active devices on the Verizon Wireless network.
  • If your company is an existing Verizon Enterprise Customer, you can contact your sales team to request UWS credentials.

Obtaining a VZ-M2M Session Token Programmatically

To send Device Location requests, you must use your UWS credentials to authenticate with the POST /api/m2m/v1/session/login endpoint at the beginning of each API session and receive a VZ-M2M session token that you must put in the header of all other API requests. To obtain a VZ-M2M session token:

  1. Follow the instructions above to get a ThingSpace token.
  2. Send a POST /api/m2m/v1/session/login request with the ThingSpace token in the header and your UWS username and password in the body.

The response will contain a sessionToken, which you can use for the VZ-M2M-Token value in the header of all subsequent requests. The token will remain valid as long as your application continues to use it, but it will expire after 20 minutes of inactivity.

Note: All API calls after the session/login request must have both the ThingSpace token and the sessionToken in the header.