Skip to main content

Create New API Key

POST 
/company/apikey/

Create a new API Key for the authenticated user associated with their company, enabling programmatic authentication for external integrations and automations.

Objective​

Generate secure API Key type credentials that allow programmatic access to the company's resources according to the specified permission type.

Use Cases​

  • Integration with external transportation management systems
  • Automation of auction creation via scripts
  • Automatic invoice generation from third-party platforms
  • Development of custom applications that consume the CargoOffer API

Limits​

  • Maximum 4 API Keys per company
  • If the limit is reached, a 403 error with code MAX_APIKEYS will be returned
  • Each key is unique and cannot be recovered once created

Operation Flow​

flowchart TD
  A[Receive Request] --> B{User Authenticated?}
  B -->|No| C[401 Unauthorized]
  B -->|Yes| D{User Exists?}
  D -->|No| E[404 USER_NOT_FOUND]
  D -->|Yes| F{Company Exists?}
  F -->|No| G[404 COMPANY_NOT_FOUND]
  F -->|Yes| H{API Keys < 4?}
  H -->|No| I[403 MAX_APIKEYS]
  H -->|Yes| J{Valid Type?}
  J -->|No| K[400 Mongoose Validation]
  J -->|Yes| L[Generate 40 char Key]
  L --> M[Generate temp_code]
  M --> N[Save to DB]
  N --> O[201 Created + Complete Key]

Important Considerations​

  • The complete API Key is only displayed at the moment of creation
  • It cannot be retrieved later and must be stored securely
  • The key includes a checksum character for validation
  • Deletions are soft deletes (mongoose-delete plugin)

Security Notes​

  • Store the API Key in a secrets manager or environment variable
  • Do not share the key in public repositories
  • Rotate keys periodically for security
  • Use the most restrictive permission type necessary

Request​

Responses​

API Key successfully created

Response Headers