Authentication

# From app/constants.py
KEY_TYPE_NORMAL = "normal"  # Live API key
KEY_TYPE_TEAM = "team"      # Team/guest list only
KEY_TYPE_TEST = "test"      # Simulated sending

# From app/models.py - ApiKey model
class ApiKey:
    id: UUID                    # Unique key ID
    name: str                   # Descriptive name (e.g., "Production key")
    service_id: UUID            # Parent service
    key_type: str               # "normal", "team", or "test"
    
    secret: str                 # Encrypted secret (for signing JWTs)
    
    created_at: datetime
    created_by_id: UUID         # User who created the key
    
    expiry_date: datetime       # When key expires (null = never)
    updated_at: datetime

# Good key names:
"production-api-key"
"staging-integration-key"
"ci-automated-tests"
"mobile-app-v2"

# Avoid:
"key1"
"test"
"asdf"

# From app/authentication/auth.py

# JWT must include:
{
  "iss": "service-id-uuid",      # Your service ID (issuer)
  "iat": 1709467800              # Unix timestamp (issued at)
}

# Signed with:
- Algorithm: HS256
- Secret: Your API key secret

# Validation rules:
- Token must be signed with valid API key secret
- iat (issued at) must be within 30 seconds of current time
- Service must exist and be active
- API key must not be expired

from notifications_python_client.notifications import NotificationsAPIClient

# Client handles JWT creation automatically
notifications_client = NotificationsAPIClient(api_key)

# JWT is created and included in Authorization header for you
notifications_client.send_email_notification(
    email_address="[email protected]",
    template_id="template-id",
)

import jwt
import time
import uuid

# Your API key details
service_id = "your-service-id-uuid"
api_key_secret = "your-api-key-secret"

# Create JWT
token = jwt.encode(
    {
        "iss": service_id,
        "iat": int(time.time())
    },
    api_key_secret,
    algorithm="HS256"
)

# Use in request
headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

# From app/authentication/auth.py - AuthError responses

# 401 Unauthorized
"Unauthorized: authentication token must be provided"
# Cause: No Authorization header

"Unauthorized: authentication bearer scheme must be used"  
# Cause: Authorization header doesn't start with "Bearer "

# 403 Forbidden
"Invalid token: service id is not the right data type"
# Cause: iss claim is not a valid UUID

"Invalid token: service not found"
# Cause: Service ID in iss claim doesn't exist

"Invalid token: service has no API keys"
# Cause: Service exists but has no API keys

"Invalid token: service is archived"
# Cause: Service has been deactivated

"Invalid token: API key not found"
# Cause: JWT signature doesn't match any API key

"Invalid token: API key revoked"
# Cause: API key has an expiry_date set

"Error: Your system clock must be accurate to within 30 seconds"
# Cause: iat timestamp is too old or too far in future

"Invalid token: algorithm used is not HS256"
# Cause: JWT signed with wrong algorithm

"Invalid token: iss field not provided"
# Cause: JWT missing iss claim

{
  "status_code": 403,
  "errors": [
    {
      "error": "AuthError",
      "message": "Invalid token: API key not found"
    }
  ]
}

# Set expiry_date to revoke
api_key.expiry_date = datetime.utcnow()

# Authentication will fail:
# "Invalid token: API key revoked"

# From app/models.py
class ApiKey:
    _secret: str  # Stored encrypted in database
    
    @property
    def secret(self):
        # Decrypted when accessed
        return signing.decode(self._secret)
    
    @secret.setter
    def secret(self, secret):
        # Encrypted before storage  
        self._secret = signing.encode(str(secret))

# From app/authentication/auth.py
current_app.logger.info(
    "API authorised for service %(service_id)s with api key %(api_key_id)s, "
    "using issuer %(issuer)s for URL: %(url)s",
    extra={
        "service_id": service_id,
        "api_key_id": api_key.id,
        "issuer": request.headers.get("User-Agent"),
        "url": request.base_url,
    }
)

import jwt
import time
import requests

# Your credentials
SERVICE_ID = "your-service-id-uuid"
API_KEY_SECRET = "your-api-key-secret"

# Create JWT
def create_jwt_token(service_id, secret):
    headers = {"typ": "JWT", "alg": "HS256"}
    
    claims = {
        "iss": service_id,
        "iat": int(time.time())
    }
    
    return jwt.encode(claims, secret, algorithm="HS256", headers=headers)

# Make authenticated request
def send_notification():
    token = create_jwt_token(SERVICE_ID, API_KEY_SECRET)
    
    headers = {
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json"
    }
    
    data = {
        "email_address": "[email protected]",
        "template_id": "template-id-uuid",
        "personalisation": {
            "name": "John"
        }
    }
    
    response = requests.post(
        "https://api.notifications.service.gov.uk/v2/notifications/email",
        json=data,
        headers=headers
    )
    
    return response.json()

# Send
result = send_notification()
print(result)