Getting Credentials to use the API

After you’ve registered on this site, you can use our simulator to try out the Connectivity Management API requests and responses. Once you’re ready to work with real devices in your own account, 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 the simulator API token or your own token to use in your application or with the API console. 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 thingspace.verizon.com.
  2. Click your name, select Account settings and click Key Management.
  3. On the home page, click My Keys to go to Key Management in your Account Settings.
  4. Copy the key and the secret and store them in a secure place for your application to use.
  5. Concatenate the key and the secret, with a colon between them, like this:
    my_key_value:my_secret_value
  6. Encode the entire string in Base64 format. (To learn more about encoding in Base64 format, visit www.base64encode.org).
  7. Send a POST request to 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" "/api/ts/v1/oauth2/token"

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

Revoking a ThingSpace Token Programmatically

You can revoke a token with this request format (user your token in place of TOKEN_TO_REVOKE), 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=TOKEN_TO_REVOKE" "/api/ts/v1/oauth2/revoke"

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

Connectivity Management Log In Credentials

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

  • If you are a developer with a ThingSpace Marketplace connectivity plan, see the “Getting Started with ThingSpace APIs” section in Getting Started.
  • If you don’t have a Verizon Enterprise account, you can sign up for a Starter Account to connect and test up to 20 devices.

  • If your company is an existing Verizon Enterprise Customer, you probably already have a UWS account and only need to set a password before using it:

    1. Log in to ThingSpace Manage at thingspace.verizonwireless.com/Portal/manage/dashboard.
    2. Click Admin in the navigation bar.
    3. Click the Users icon.
    4. Look in the “Role” column for the “Unified Web Services” user, and click the pencil icon on the right to edit the user.
    5. Note the User name shown for the user. You’ll need it to send API requests.
    6. Enter a Password for the user, and then enter the same password in the Confirm Password field.
    7. Click Save.

You can now use the user name and password log in to a UWS account, such as with the POST /session/login request.

If your company is an existing Verizon Enterprise Customer and you do not see a Unified Web Services user in ThingSpace Manage, contact your sales team to request UWS credentials.

Unified Web Services (UWS) credential requirements

UWS Username Requirements:

- Username must be at least 2 characters long

- Username should not exceed 32 characters long

UWS Password Requirements:

- Must be between 8 -32 characters long

- Must contain at least one upper case letter

- Must contain at least one lower case letter

- Must contain at least one number/digit

- Must contain at least one symbol/Special character Note: Invalid characters include ; & < > [ ] , .' \" /

- Must NOT contain common sequences of characters such as '12345' or 'qwerty'

Obtaining a Connectivity Management Token Programmatically

You use the Connectivity Management credentials with the POST /session/login request to authenticate at the beginning of each API session and receive a session token that you must put in the header of all other API requests. To obtain a Connectivity Management token:

  1. Follow the instructions above to get a ThingSpace token.
  2. Send a POST /session/login request with the ThingSpace token in the header and your Connectivity Management 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.

Notes:

  • UWS credentials are machine credentials, not people credentials. Your company only needs one set of UWS credentials, not a set for every developer.
  • If your company ignores the previous bullet and has different UWS credentials for every developer, you need to notify your Account Representative to delete old credentials when a developer leaves the company.
  • UWS credentials can only be used by your application to log in through the APIs.
  • You cannot use portal credentials with the APIs, and you can’t use UWS credentials to access the portals.
  • UWS credentials do not expire, but it is recommended that you create a new password every three months.