SecurePost API Documentation

Overview

SecurePost is a JWT-authenticated REST API service for sending SMS, EMAIL, and PUSH messages.
The API uses OAuth 2.0-style token-based authentication with short-lived JWT tokens (3-minute expiry) for enhanced security.

Base URL:
https://fakecomworld.endpoint/securepost

---

Authentication

SecurePost uses JWT (JSON Web Token) authentication.
You must first obtain a token, then include it in subsequent API requests.

---

Step 1: Obtain Access Token

Endpoint:
POST /securepost/auth

Request Body:

{
  "clientId": "securepost-client-id",
  "clientSecret": "securepost-secret-key"
}

Success Response (200 OK):

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenType": "Bearer",
  "expiresIn": 180,
  "issuedAt": "2024-01-15T10:30:00Z"
}

Token Properties

Field	Type	Description
accessToken	string	JWT token to use for authenticated requests
tokenType	string	Always "Bearer" — use this prefix in Authorization header
expiresIn	integer	Token validity in seconds (180 = 3 minutes)
issuedAt	datetime	UTC timestamp when token was issued

---

Step 2: Use Token in Requests

Include the token in the Authorization header for all protected endpoints:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Important: Tokens expire (by default) after 3 minutes.
Implement token refresh logic in your client.

---

Required Headers

Header	Type	Required	Description
X-STUDENT-GROUP	string	Yes	Your student group identifier
Authorization	string	Yes (except /token)	Bearer token: Bearer {accessToken}
Content-Type	string	Yes	Must be application/json

---

Endpoints

Send Message

Send a message to a single recipient.

Endpoint:
POST /securepost/message

Request Body:

{
  "format": "EMAIL",
  "recipient": "user@example.com",
  "body": "Your message content here",
  "subject": "Message Subject"
}

Request Schema

Field	Type	Required	Description
format	enum	Yes	Message format: "SMS", "EMAIL", or "PUSH"
recipient	string	Yes	Single recipient address (phone, email, or device ID)
body	string	Yes	The message content
subject	string	No	Message subject (primarily for EMAIL format)

---

Success Response (200 OK)

{
  "delivered": true,
  "trackingId": "A1B2C3D4E5F67890ABCDEF1234567890",
  "errorMessage": null,
  "deliveryTimestamp": "2024-01-15T10:35:42Z"
}

Response Schema

Field	Type	Description
delivered	boolean	Indicates if the message was delivered successfully
trackingId	string	Unique tracking identifier (32-character hex string)
errorMessage	string	Error description if delivery failed, null on success
deliveryTimestamp	datetime	UTC timestamp when message was delivered

---

Error Responses

• 401 Unauthorized — Missing or invalid token
• 401 Unauthorized — Expired token
• 400 Bad Request — Missing required field
• 400 Bad Request — Missing X-STUDENT-GROUP
• 429 Too Many Requests — Rate limit exceeded (check headers)
• 500 Internal Server Error
• 503 Service Unavailable
• 504 Gateway Timeout

---

Rate Limiting

SecurePost enforces rate limiting to ensure fair usage.

Default limits:

• 10 requests/minute per student group for /message endpoint
• 3 requests/minute per student group for /auth endpoint
• Rate limit window: 60 seconds (sliding window)

When exceeded, a 429 Too Many Requests response is returned.
Check the response headers for additional rate limit details.

---

Response Times

SecurePost simulates realistic network conditions & outages.

---

Support

For issues or questions, please contact your instructor or check the project documentation.