Learn how to make authenticated API requests to 23shout.

All requests to the 23shout API must be authenticated with credentials unique to your account. Two strings are included, your Access Key ID, and your Secret Access Key. Both are needed to complete authentication, and both are included as URL parameters.

Creating your Access Keys

To generate these keys is simple.

  • Sign into your 23shout account
  • Click your avatar in the top right, and select Settings
  • From the menu on the left side, select Access Keys
  • From here you can see Access Keys created for your account, and when it was last used
  • Let's create a new Access Key now by selecting the Create your first Access Key button
  • Name your Access Key and click Continue

Your new Access Key ID and Secret Access Key will now appear for you to copy. Make note of these separately.

📘

Important note

Every request will be processed as though your account made them, this means messages will show as sent by your name, and similarly, scheduled calls will be shown as scheduled by you.

For this reason, you may wish to create a separate account dedicated to holding Access Keys. Accounts that are deactivated will lose any active Access Keys associated with them.

Authenticating your requests

In order to authenticate your requests with our API you'll need to include two URL parameters with each request, access_key_id which will hold your Access Key ID, and access_key_secret which in turn holds your Secret Access Key.

Below we make an example request to the API to retrieve our current user.

import requests

# You should store these as environment variables!
# Don't commit these to git!
access_key_id = "example_key_id"
access_key_secret = "example_key_secret"

requests.get(
  "https://api.23shout.com/prod/v1/user/me",
  params={
    'access_key_id': access_key_id,
    'access_key_secret': access_key_secret,
  }
)

Storing your credentials

It's highly advised that you do not store these credentials in your projects code or commit them to git.

Instead we recommend you make use of Environment Variables. In this example we'll use two variables named SHOUT_ACCESS_KEY_ID and SHOUT_ACCESS_KEY_SECRET.

The example below will set the variables in your shell for this session only, refer to your cloud providers documentation on setting variables for your application, or edit your ~/.bashrc file to include the following.

export SHOUT_ACCESS_KEY_ID="example_key_id"
export SHOUT_ACCESS_KEY_SECRET="example_key_secret"
$env:SHOUT_ACCESS_KEY_ID="example_key_id"
$env:SHOUT_ACCESS_KEY_SECRET="example_key_secret"
set SHOUT_ACCESS_KEY_ID="example_key_id"
set SHOUT_ACCESS_KEY_SECRET="example_key_secret"

To use these in your code is simple, let's edit the example from the previous section to be a bit more secure.

import os

import requests

# These pull the credentials from the host machine, this example
# is completely safe to commit to version control. :)
access_key_id = os.environ.get("SHOUT_ACCESS_KEY_ID")
access_key_secret = os.environ.get("SHOUT_ACCESS_KEY_SECRET")

requests.get(
  "https://api.23shout.com/prod/v1/user/me",
  params={
    'access_key_id': access_key_id,
    'access_key_secret': access_key_secret,
  }
)

And that's it. You're now all ready to go with sending requests. :smiley: