darkhelm/notifications-admin
1
0
Fork 0
mirror of https://github.com/GSA/notifications-admin.git synced 2026-02-05 02:42:26 -05:00
Code Issues Packages Projects Releases Wiki Activity

Add section from existing doc, to add more details

Browse Source
This commit is contained in:
catherineheywood
2016-04-11 16:27:23 +01:00
parent ffe47201a5
commit b0dc5b5d5f
1 changed files with 36 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

39
docs/index.md
View File

@@ -59,7 +59,7 @@ There are two ways to integrate the API into your service:
* use a client library provided by Notify - there is currently 1 python library but more will be added in different languages
* develop your own integration to produce requests in the correct format
GOV.UK.Notify uses [JWT tokens](https://jwt.io/) for authentication and identification. JWT tokens are built into our pre-built client library. If you don't use the GOV.UK Notify client library, you must manually create the token yourself.
GOV.UK.Notify uses [JWT tokens](https://jwt.io/) for authentication and identification. JWT tokens are built into the GOV.UK Notify client library. If you don't use this library, you must manually create the token yourself.
A JWT token contains, in encrypted format:
* your service ID - identifies your service
@@ -71,6 +71,39 @@ Use the [GOV.UK Notify](https://www.notifications.service.gov.uk/) web applicati
**Important:** API keys are secret, so save them somewhere safe. Do not commit API keys to public source code repositories.
[Information below needs to be expanded]
JWT tokens have a series of standard and application-specific claims.
GOV.UK Notify standard claims:
```
{
"typ": "JWT",
"alg": "HS256"
}
```
GOV.UK Notify application-specific claims:
```
{
iss: 'string', // service id
iat: 0, // creation time in epoch seconds (UTC)
req: 'string', // signed request
pay: 'string', // signed payload (POST requests only)
}
```
Notify API tokens sign both the request being made, and for POST requests, the payload.
The signing algorithm is HMAC signature, using provided key SHA256 hashing algorithm.
Request signing is of the form HTTP METHOD PATH.
```
GET /notification/1234
```
Payload signing requires the actual payload to be signed, NOT the JSON object. Serialize the object first then sign the serialized object.
API endpoints
----------------
@@ -152,8 +185,8 @@ GET /notifications/{id}
```
where
* ‘status’ is the the status of the notification.
* 'status' can be 'sending', 'delivered', 'failed'
* 'method' is sms or email
* 'status' can be 'sending', 'delivered', 'failed' [change status in message above?]
* 'method' is 'sms' or 'email'
* 'job_id' is the unique identifier for the process of sending the notification
* 'message' is the content of message
* 'sender' may be the provider [?]