API authentication is done using OAuth 2.0 (RFC 6749), which provides a secure way for you to interact with our service without sending passwords over the network or needing to ask your users for their login credentials (which you must never do).
If you're developing a desktop or a mobile client that will be distributed to anyone other than yourself, the steps here don't apply. Please get in touch, and we'll set up an implicit grant method for you.
Here's how API authentication works:
Send your user to a special link on this site, which will let them authorize your software to access their data.
We will redirect the user's browser back to your site using a URL that you specificy, including an authorization code (or an error message).
Trade the authorization code for an access token, which you can then use to access the user's data via the API.
Step 1: User Authorizes Your Application
Start by sending your user to the following URL:
Include the following query parameters in the request:
code.
The user will be prompted to log in and then be given information about your application and the permissions you're requesting, with the option of allowing or denying the request.
If the user has previously authorized your application to access the requested scope, they will be prompted to log in (if necessary), but will then be immediately redirected back to your app without having to allow access a second time.
Once the user has either approved or denied your request, their browser
will be redirected back to the callback URL that we have on file for
your client. The response will contain either a code query parameter
(if approved) or an error query parameter (if denied).
Possible Errors
For errors related to your client_id, we will display a message to the user asking them to get in contact with you.
If we can identify the client_id but the request is invalid for some
reason, we will sent the user to your callback URL with error and
error_description parameters to help you troubleshoot what
happened.
Your code can look at the error parameter and react accordingly. It
should not use the error_description except to show it to you, as we
may revise it in the future without warning or notice.
invalid_request: The request contained missing or duplicate parameters.invalid_scope: You've asked for permissions that don't exist.unsupported_response_type: We only support authorization codes at this time.unauthorized_client: Your client access is either not set up properly or has been disabled for some reason. Please contact us.temporarily_unavailable: Either API access is currently unavailable for maintenance or some other reason, or else your client access is being throttled. The error description will contain more detail. Contact us if it's a throttling issue, and direct the user to try again later.
Step 2: Exchange the Authorization Code for a Token
Once the user has been redirect back to your site and you have an authorization code, you then need to exchange that code for a token.
Use Basic authentication to set your client_id (as the username) and
client_secret (as the password), if possible. If your HTTP library
doesn't support Basic authentication, you can include them as query
parameters instead.
Include the following query parameters in the request:
authorization_code.
Sample Response
Under normal circumstances, we will respond with a JSON object whether or not your request is successful, but you should verify this by checking the Content-Type header.
A successful response will look like this:
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token" : "kjxwnpkj4ho139pckj8h4pp4jvb73lb0",
"token_type" : "bearer"
}
An error response will look like this:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error" : "invalid_grant",
"error_description" : "The requested authorization has expired."
}
If the request was successful, you can now delete the authorization code and store the access token. You will use this for future API calls on behalf of the user, instead of your client credentials.
Possible Errors
The following HTTP status and error codes may be returned:
400 invalid_client: You need to identify yourself, either in a Basic Authorization header, or by includingclient_idandclient_secretquery parameters.400 invalid_grant: The specified authorization code doesn't exist, has already been used, or has expired.400 invalid_request: A required parameter was omitted or was included more than once.400 unsupported_grant_type: We only supportauthorization_codegrants at this time.401 invalid_client: Your client credentials were not recognized, or you access has been temporarily or permanently blocked. Please contact us.429 invalid_client: Your client access is being throttled. Please contact us.
Step 3: Make API Calls
Once you have an access token, you're all set to make API calls. You'll need to include the access token with every request. We support both of the methods included in the OAuth specification, plus a third:
The recommended method is to use a "Bearer" Authorization header in your request, such as the following:
Authorization: Bearer kjxwnpkj4ho139pckj8h4pp4jvb73lb0If you're using an OAuth library for your language, it will probably have built-in support for this authentication method. If you're using an HTTP library, you should be able to set the Authorization header manually.
If your HTTP library doesn't let you set the Authorization header, you may instead set an
access_tokenquery parameter. This can be useful for testing from the command line or in a browser.https://https://www.prayerletters.com/api/v1/dev/ping?access_token=kjxwnpkj4ho139pckj8h4pp4jvb73lb0For HTTP clients that support Basic authentication but don't let you set the header manually, you can enter your access token as the username. We will ignore the password, so you can leave it blank.