OpenAPI Specification
openapi: 3.1.0
info:
title: Wove External Authentication API
version: 1.0.0
description: "# Wove External API Documentation\n\nThe Wove External API allows you to programmatically access document processing, shipment management, and validation capabilities.\n\n## Features\n\n- **OAuth 2.0 Authentication**: Secure client credentials flow\n- **Rate Limiting**: Configurable per-client rate limits\n- **Document Processing**: Upload, validate, and merge shipping documents\n- **Shipment Management**: Create and manage shipment records with validation and merge operations\n- **Webhooks**: Get notified of document processing events (extraction, validation, merge)\n- **Comprehensive Error Handling**: Detailed error responses with troubleshooting information\n\n## Getting Started\n\n1. **Create OAuth Client**: Contact your account manager to create OAuth credentials\n2. **Get Access Token**: Use client credentials flow to obtain bearer token\n3. **Make API Calls**: Include bearer token in Authorization header\n4. **Handle Rate Limits**: Monitor rate limit headers in responses\n\n## Authentication\n\nAll API endpoints require OAuth 2.0 authentication using the client credentials flow.\n\n### Getting an Access Token\n\n```bash\ncurl -X POST https://api.wove.com/api/v1/external/auth/token \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"grant_type\": \"client_credentials\",\n \"client_id\": \"your_client_id\",\n \"client_secret\": \"your_client_secret\"\n }'\n```\n\n### Using the Access Token\n\nInclude the access token in the Authorization header:\n\n```bash\ncurl -H \"Authorization: Bearer your_access_token\" \\\n https://api.wove.com/api/v1/external/shipments\n```\n\n## Rate Limiting\n\nAll endpoints are subject to rate limiting based on your OAuth client configuration:\n\n- **Per-minute limit**: Default 60 requests/minute\n- **Daily limit**: Default 10,000 requests/day\n\nRate limit information is included in response headers:\n- `X-RateLimit-Limit-Minute`: Your per-minute limit\n- `X-RateLimit-Remaining-Minute`: Remaining requests this minute\n- `X-RateLimit-Reset-Minute`: When the minute window resets\n- `X-RateLimit-Limit-Day`: Your daily limit\n- `X-RateLimit-Remaining-Day`: Remaining requests today\n- `X-RateLimit-Reset-Day`: When the daily window resets\n\n## Webhook Security\n\nAll webhook payloads are signed using HMAC-SHA256 for verification:\n\n```javascript\n// Verify webhook signature\nconst crypto = require('crypto');\nconst signature = request.headers['x-wove-signature'];\nconst payload = JSON.stringify(request.body);\nconst expectedSignature = crypto\n .createHmac('sha256', your_webhook_secret)\n .update(payload)\n .digest('hex');\n\nconst isValid = crypto.timingSafeEqual(\n Buffer.from(signature),\n Buffer.from(expectedSignature)\n);\n```\n\nHeaders included with every webhook:\n- `X-Wove-Signature`: HMAC-SHA256 signature of the payload\n- `X-Wove-Event`: Event type (e.g., \"extraction.completed\")\n- `X-Wove-Timestamp`: ISO timestamp when the webhook was sent\n\n## Error Handling\n\nAll errors follow a consistent format:\n\n```json\n{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"One or more documents not found or access denied\",\n \"details\": {\n \"field\": \"documentIds\",\n \"value\": [\"invalid_id\"]\n }\n }\n}\n```\n\n### Error Codes\n\n- `VALIDATION_ERROR` - Invalid request parameters or data validation failure\n- `AUTHENTICATION_ERROR` - Invalid or expired credentials\n- `AUTHORIZATION_ERROR` - Insufficient permissions for the requested operation\n- `NOT_FOUND` - Requested resource not found\n- `RATE_LIMIT_ERROR` - Too many requests, rate limit exceeded\n- `INTERNAL_ERROR` - Internal server error\n\nSee the common error responses in the components section for detailed examples.\n"
contact:
name: Wove API Support
email: api-support@wove.com
url: https://docs.wove.com
license:
name: Proprietary
url: https://wove.com/terms
servers:
- url: https://api.wove.com
description: Production server
- url: https://staging-api.wove.com
description: Staging server
- url: http://localhost:4000
description: Development server
security:
- bearerAuth: []
tags:
- name: Authentication
description: OAuth 2.0 authentication endpoints
paths:
/api/v1/external/auth/token:
post:
tags:
- Authentication
summary: Get OAuth access token
description: 'Obtain an access token using OAuth 2.0 client credentials flow.
This token is required for all other API endpoints.
**Rate Limiting**: 100 requests per minute per IP address.
'
security: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TokenRequest'
example:
grant_type: client_credentials
client_id: wove_prod_abc123def456
client_secret: sk_your_secret_key
scope: shipments:read documents:read validation:create
responses:
'200':
description: Access token generated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/TokenResponse'
example:
access_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
token_type: Bearer
expires_in: 3600
scope: shipments:read documents:read validation:create
'400':
description: Invalid request parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Invalid client credentials
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/v1/external/auth/revoke:
post:
tags:
- Authentication
summary: Revoke OAuth token
description: 'Revoke an OAuth access token to immediately invalidate it.
This is useful when a token is compromised or no longer needed.
'
security:
- bearerAuth: []
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
token:
type: string
description: 'The token to revoke (optional, defaults to current token)
'
token_type_hint:
type: string
enum:
- access_token
- refresh_token
description: Hint about the token type
responses:
'200':
description: Token revoked successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
example:
success: true
data:
revoked: true
message: Token revoked successfully
'401':
description: Invalid or expired token
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
TokenRequest:
type: object
properties:
grant_type:
type: string
enum:
- client_credentials
example: client_credentials
client_id:
type: string
example: wove_prod_abc123...
client_secret:
type: string
example: sk_...
scope:
type: string
description: Space-separated list of scopes
example: shipments:read documents:read validation:create
required:
- grant_type
- client_id
- client_secret
SuccessResponse:
type: object
properties:
success:
type: boolean
example: true
data:
type: object
description: Response data (varies by endpoint)
message:
type: string
description: Optional success message
required:
- success
- data
TokenResponse:
type: object
properties:
access_token:
type: string
example: eyJhbGciOiJIUzI1NiIs...
token_type:
type: string
example: Bearer
expires_in:
type: integer
example: 3600
description: Token lifetime in seconds
scope:
type: string
example: shipments:read documents:read validation:create
ErrorResponse:
type: object
properties:
success:
type: boolean
example: false
error:
type: object
properties:
code:
type: string
example: VALIDATION_ERROR
message:
type: string
example: Invalid input parameters
details:
type: object
description: Additional error context
required:
- success
- error
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: OAuth 2.0 Bearer token obtained from /auth/token endpoint