Overview

Authenticate with the PartsSource APIs using OAuth 2.0

The PartsSource APIs use JWT Bearer Token authentication via AWS Cognito. All API requests (except health checks) require a valid access token.

---

Quick Start

1. Get an Access Token

curl -X POST https://auth.partssource.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=default-m2m-resource-server-p2hkah/admin:internal"

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

2. Use the Token

Include the token in the Authorization header:

curl -X GET https://api.partssource.com/internal/api/companies/12345 \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

---

Authentication Flow

The APIs use the OAuth 2.0 Client Credentials flow, designed for machine-to-machine (M2M) integration:

Your Application                    Auth Server                      API
      |                                  |                            |
      |-- POST /oauth2/token ----------->|                            |
      |   (client_id, client_secret)     |                            |
      |                                  |                            |
      |<-- access_token -----------------|                            |
      |                                  |                            |
      |-- GET /api/resource ---------------------------------->|
      |   (Authorization: Bearer token)                        |
      |                                  |                            |
      |<-- Response -------------------------------------------|

---

Token Details

Property	Value
Type	JWT (JSON Web Token)
Expiration	1 hour (3600 seconds)
Algorithm	RS256
Issuer	AWS Cognito User Pool

Token Lifecycle

1. Request - Exchange credentials for access token

2. Use - Include token in API requests

3. Refresh - Request new token before expiration

4. Expire - Token becomes invalid after 1 hour

Tokens expire after 1 hour. Implement token refresh logic to avoid service interruption. See Token Management for best practices.

---

API Scopes

Scopes define what resources your application can access.

InternalApi Scopes

Scope	Access Level
default-m2m-resource-server-p2hkah/admin:internal	Full InternalApi access

CustomerApi Scopes

Scope	Access Level
default-m2m-resource-server-p2hkah/customer:read	Read customer data
default-m2m-resource-server-p2hkah/customer:write	Create/update customer data

Request the appropriate scope when obtaining your token:

-d "scope=default-m2m-resource-server-p2hkah/admin:internal"

---

Authentication Endpoints

Endpoint	URL	Purpose
Token	https://auth.partssource.com/oauth2/token	Exchange credentials for token
JWKS	https://auth.partssource.com/.well-known/jwks.json	Public keys for token validation
Discovery	https://auth.partssource.com/.well-known/openid-configuration	OpenID Connect configuration

---

Error Responses

401 Unauthorized

Returned when authentication fails:

{
  "type": "https://tools.ietf.org/html/rfc7235#section-3.1",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authentication is required to access this resource.",
  "correlationId": "0HN7QJKV3QJ8K:00000001"
}

Common causes:

• Missing Authorization header

• Invalid or malformed token

• Expired token

• Token signature validation failed

403 Forbidden

Returned when authentication succeeds but authorization fails:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.3",
  "title": "Forbidden",
  "status": 403,
  "detail": "You do not have permission to access this resource.",
  "correlationId": "0HN7QJKV3QJ8K:00000001"
}

Common causes:

• Token lacks required scope

• Attempting cross-tenant access (CustomerApi)

• User doesn't have facility access

---

Next Steps

• Obtaining Tokens - Detailed token request guide

• Token Management - Best practices and error handling

• Request API Access - How to get your credentials