Create API Key 🔒

Creates a new API key. The key value is automatically generated by the system.

Endpoint

POST /api/ApiKey/create

🔒 JWT Required

x-api-key: <your-api-key>Authorization: Bearer <jwt-token>Content-Type: application/json

Authentication Required

🔒 JWT Required - Both API key and JWT token are required

Request Example

bash

curl -X POST https://shipyo.it/api/ApiKey/create \
  -H "x-api-key: ak_1234567890abcdef" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mobile App API Key",
    "allowedIp": "192.168.1.200",
    "isActive": true,
    "description": "API key for mobile application integration"
  }'

Request Body

json

{
  "name": "Mobile App API Key",
  "allowedIp": "192.168.1.200",
  "isActive": true,
  "description": "API key for mobile application integration"
}

Fields:

name (string, required): Human-readable name for the API key
allowedIp (string, optional): IP address restriction (null for no restriction)
isActive (boolean, required): Whether the API key should be active immediately
description (string, optional): Description of the API key's purpose

Success Response

201 API Key Created Successfully

New API key has been generated with secure random value

Example Response:

{
  "success": true,
  "data": {
    "id": 3,
    "key": "ak_3456789012bcdef3456789012",
    "name": "Mobile App API Key",
    "isActive": true,
    "description": "API key for mobile application integration",
    "allowedIp": "192.168.1.200",
    "createdDate": "2024-08-25T15:30:00Z",
    "permissions": [
      "read",
      "write"
    ],
    "tenantId": 1,
    "expiresAt": null
  },
  "message": "API Key created successfully"
}

Response Fields

Field	Type	Description	Security Notes
`success`	boolean	Always `true` for successful creation	Operation status
`data.id`	number	Unique API key identifier	Use for management operations
`data.key`	string	ACTUAL API KEY VALUE	⚠️ Store securely - shown only once
`data.name`	string	Human-readable API key name	For identification purposes
`data.isActive`	boolean	API key activation status	Must be true to use
`data.description`	string	Purpose description	Documentation
`data.allowedIp`	string/null	IP address restriction	Security constraint
`data.createdDate`	string	ISO timestamp of creation	Audit information
`data.permissions`	array	Granted permissions	Access scope
`data.tenantId`	number	Associated tenant ID	Scope limitation
`data.expiresAt`	string/null	Expiration date	null = no expiration
`message`	string	Success confirmation	Human-readable message

🔒 Critical Security Information

API Key Value - First and Only Display

🚨 Store Immediately: The key value is only shown once upon creation
🔐 Secure Storage: Store in environment variables or secure configuration
❌ Cannot Retrieve: You cannot get the full key value again later
🔄 Regeneration: If lost, you must create a new API key

IP Address Restrictions

🌐 allowedIp: If set, API key only works from this IP address
🔓 null value: No IP restriction (works from any IP - less secure)
🛡️ Security recommendation: Always set IP restrictions for production

Immediate Usage

bash

# Test the newly created API key immediately
curl -X GET https://shipyo.it/api/Token/generate-from-apikey \
  -H "x-api-key: ak_3456789012bcdef3456789012"

Post-Creation Actions

Immediate steps required:

💾 Save the key value in your application's secure configuration
🧪 Test the key with a simple API call to verify it works
📝 Document usage in your deployment notes
🔍 Set up monitoring for key usage patterns
📅 Plan rotation schedule for security best practices

Important Notes

Tenant Scope: API key is automatically associated with your current tenant
Permissions: Inherit from your user role and tenant policies
Activation: Key is immediately active and ready to use
Management: Use the returned id for future update/delete operations
Audit: Key creation is logged for security monitoring

Next Steps

Store the key securely in your application
Update your application to use the new API key
Test all integrations with the new key
Monitor usage through API logs
Schedule regular rotation for enhanced security

Error Responses

400 Bad Request

Request contains invalid data or validation failures

Example Response:

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    "Name is required",
    "allowedIp must be a valid IP address"
  ]
}

Common validation errors:

Missing required name field
API key name already exists within tenant
Invalid IP address format in allowedIp
Name contains invalid characters
Description too long (if limits apply)

401 Unauthorized

Authentication credentials are missing or invalid

Example Response:

{
  "success": false,
  "message": "API Key is missing.",
  "errors": [
    "Missing x-api-key header"
  ]
}

Authentication issues:

Missing x-api-key header
Invalid API key value
Missing Authorization: Bearer <token> header
JWT token expired or invalid
Malformed authentication headers

403 Forbidden

Valid credentials but insufficient permissions to create API keys

Example Response:

{
  "success": false,
  "message": "Forbidden - Insufficient permissions",
  "errors": [
    "Cannot create API keys"
  ]
}

Permission issues:

User role does not allow API key creation
Tenant-level API key creation restrictions
Maximum API key limit reached for tenant
Cross-tenant API key creation denied

409 Conflict

API key name already exists within the tenant

Example Response:

{
  "success": false,
  "message": "API key name already exists",
  "errors": [
    "An API key with this name already exists"
  ]
}

Conflict scenarios:

Another API key in the same tenant has the same name
Case-insensitive name collision
Concurrent API key creation with same name

Resolution: Choose a different name or update the existing API key

422 Unprocessable Entity

Request violates business rules or system constraints

Example Response:

{
  "success": false,
  "message": "API key limit exceeded",
  "errors": [
    "Tenant has reached maximum API key limit of 10"
  ]
}

Business rule violations:

Tenant has reached maximum API key limit
IP address is in a blocked range
Name violates naming conventions
Requested permissions not available for tenant tier
API key creation temporarily disabled for tenant

500 Internal Server Error

Unexpected server error during API key creation

Example Response:

{
  "success": false,
  "message": "Internal server error",
  "errors": [
    "Failed to generate API key"
  ]
}

Possible causes:

Database connection failure
API key generation service unavailable
Cryptographic key generation errors
Internal workflow failures

Client action: Retry the request or contact support if persistent

Important Security Notes

Key Generation

API key values are automatically generated by the system
Keys follow a secure format (e.g., ak_ prefix + random string)
Key values are cryptographically secure and unique

First and Only Display

⚠️ The full API key is only shown once upon creation
Store the key value securely immediately after creation
You cannot retrieve the full key value later for security reasons

IP Restrictions

Use allowedIp to restrict API key usage to specific IP addresses
Set to null or omit for no IP restriction (less secure)
IP restrictions provide an additional security layer

Best Practices

Naming Convention

Use descriptive names that indicate purpose
Include environment (e.g., "Production Web App", "Dev Mobile")
Avoid generic names like "API Key 1"

Security Recommendations

Set allowedIp when possible for enhanced security
Create separate keys for different applications/environments
Set isActive: false initially if key needs approval process
Document the purpose in the description field

Key Management

Regularly audit and rotate API keys
Deactivate unused keys promptly
Monitor key usage through logs and analytics
Implement key expiration policies when available

Post-Creation Steps

After creating an API key:

Save the Key: Store the key value in your application's secure configuration
Test the Key: Verify the key works with a simple API call
Document Usage: Record where and how the key is being used
Monitor Access: Set up monitoring for key usage patterns
Plan Rotation: Schedule regular key rotation for security

Example Usage After Creation

bash

# Test the newly created API key
curl -X GET https://shipyo.it/api/User/getAll \
  -H "x-api-key: ak_3456789012bcdef3456789012" \
  -H "Authorization: Bearer your-jwt-token"

Create API Key 🔒 ​

Endpoint ​

Request Example ​

Request Body ​

Success Response ​

201 API Key Created Successfully

Example Response:

Response Fields ​

🔒 Critical Security Information ​

API Key Value - First and Only Display ​

IP Address Restrictions ​

Immediate Usage ​

Post-Creation Actions ​

Important Notes ​

Next Steps ​

Error Responses ​

400 Bad Request

Example Response:

401 Unauthorized

Example Response:

403 Forbidden

Example Response:

409 Conflict

Example Response:

422 Unprocessable Entity

Example Response:

500 Internal Server Error

Example Response:

Important Security Notes ​

Key Generation ​

First and Only Display ​

IP Restrictions ​

Best Practices ​

Naming Convention ​

Security Recommendations ​

Key Management ​

Post-Creation Steps ​

Example Usage After Creation ​

Create API Key 🔒

Endpoint

Request Example

Request Body

Success Response

Response Fields

🔒 Critical Security Information

API Key Value - First and Only Display

IP Address Restrictions

Immediate Usage

Post-Creation Actions

Important Notes

Next Steps

Error Responses

Important Security Notes

Key Generation

First and Only Display

IP Restrictions

Best Practices

Naming Convention

Security Recommendations

Key Management

Post-Creation Steps

Example Usage After Creation