Zipwhip API: credentials and authentication

engineering blog banner

Key takeaways

  • Managing Zipwhip credentials
  • Retrieving API credentials
  • Managing credential lifecycle

Zipwhip authentication

Almost every organization that looks into using Zipwhip for automated text messaging is going to look at Zipwhip’s API. Having assisted several customers make the crawl, walk, run steps through interfacing with Zipwhip’s API, there are a few hurdles you should be aware of before you embark on the process of integrating Zipwhip into your system.

  • Undestanding Zipwhip’s authentication mechanism
  • Understanding the lifecycle of Zipwhip’s authentication token

Managing lines and authentication

Zipwhip’s API relies on a session to authenticate API requests for our Messaging API. This is different from other messaging APIs that use an apiKey in conjunction with a secret. In Zipwhip’s case, when a request is made with a session, then the system performs the action based on the static phone number associated with the provided session.

A Zipwhip session does not expire. To expire a session, you must use the user/logout API request.

Because a session does not expire, we recommend that you persist the retrieved session in a database. In the database, you must map the text-enabled phone number to the session.

We recommend that you do not hardcode this session into your code base. If an infinite loop occurs in your system, then it is much easier to delete a database row than redeploying code.

User login

User login allows you, as the caller, to retrieve a session and then make additional API Requests, such as sending a message or adding a new contact to your account.

A session can be tied to either a phone number or a specific Operator assigned to a phone number.

An example request for a line level session

$ curl -X POST \

  --data-urlencode username=8448982526 \

  --data-urlencode password='yourReallyStrongPassword'

An example response to a line level request


  "response": "d7c4f618-23de-4655-8fca-fdfbe1530c21:123456789",

  "success": true


The response value is the session for this line.

An example request for an operator level session

$ curl -X POST \

  --data-urlencode username='user@8448982526' \```SH

  --data-urlencode password='yourReallyStrongPassword'

An example response to an operator level request


  "response": "a3a2aa43-45ca-7879-8afa-aebcf1530e32:123456789",

  "success": true


The response value is the session for this user associated with a specific line.

User logout

As mentioned previously, a Zipwhip session does not expire. Therefore, as the implementer, you must to forcibly expire a session when it is appropriate for your business. Once a session is expired, all further Messaging API requests fail. The failure is due to an authorization error.

We recommend performing a key rotation on a regular basis. This rotation includes re-authenticating a line and then expiring the previous valid session. We typically see businesses perform this action monthly.

An example logout request

$ curl -X POST \

  --data-urlencode session='d7c4f618-23de-4655-8fca-fdfbe1530c21:123456789'

An example logout response


"response": null,

"success": true


More API support + readings here.

Share on facebook
Share on linkedin
Share on twitter
Share on email
  • Related Posts

Start texting today with a free trial of Zipwhip