Create API Key Create a new API key for programmatic access to your AstraCollab storage. API keys are used to authenticate API requests.
Endpoint Request Body Field Type Required Description namestring Yes Descriptive name for the API key permissionsarray No Array of permissions (default: all permissions) expiresAtstring No ISO 8601 expiration date (default: never expires)
Example Request curl -X POST "https://api.astracollab.app/v1/keys" \ -H "Authorization: Bearer your-api-key-here" \ -H "Content-Type: application/json" \ -d '{ "name": "Production App Key", "permissions": ["files:read", "files:write", "folders:read"], "expiresAt": "2024-12-31T23:59:59Z" }'
Response { "success" : true , "data" : { "key" : { "id" : "key_1234567890abcdef" , "name" : "Production App Key" , "prefix" : "ak_1234" , "fullKey" : "ak_1234567890abcdefghijklmnopqrstuvwxyz" , "permissions" : [ "files:read" , "files:write" , "folders:read" ], "createdAt" : "2024-01-15T10:30:00Z" , "expiresAt" : "2024-12-31T23:59:59Z" , "lastUsedAt" : null , "isActive" : true } } }
The full API key is only shown once when created. Make sure to copy and store it securely. You won’t be able to retrieve the full key again.
API Key Object Properties Property Type Description idstring Unique key identifier namestring Descriptive name for the key prefixstring First 7 characters of the key (for identification) fullKeystring Complete API key (only shown on creation) permissionsarray Array of granted permissions createdAtstring ISO 8601 timestamp of creation expiresAtstring ISO 8601 expiration date (null if never expires) lastUsedAtstring ISO 8601 timestamp of last usage (null if never used) isActiveboolean Whether the key is currently active
Available Permissions Permission Description files:readRead files and metadata files:writeUpload, update, and delete files folders:readList and view folders folders:writeCreate, update, and delete folders keys:readView API keys keys:writeCreate and manage API keys billing:readView billing information adminFull administrative access
Error Responses Invalid Name { "success" : false , "error" : { "code" : "INVALID_KEY_NAME" , "message" : "Key name cannot be empty or contain invalid characters" , "details" : { "name" : "" , "reason" : "Name cannot be empty" } } }
Invalid Permissions { "success" : false , "error" : { "code" : "INVALID_PERMISSIONS" , "message" : "Invalid permissions specified" , "details" : { "invalidPermissions" : [ "invalid:permission" ], "validPermissions" : [ "files:read" , "files:write" , "folders:read" , "folders:write" , "keys:read" , "keys:write" , "billing:read" , "admin" ] } } }
Invalid Expiration Date { "success" : false , "error" : { "code" : "INVALID_EXPIRATION_DATE" , "message" : "Expiration date must be in the future" , "details" : { "expiresAt" : "2023-01-01T00:00:00Z" , "currentTime" : "2024-01-15T10:30:00Z" } } }
Key Limit Exceeded { "success" : false , "error" : { "code" : "KEY_LIMIT_EXCEEDED" , "message" : "Maximum number of API keys reached" , "details" : { "currentKeys" : 10 , "maxKeys" : 10 } } }
SDK Examples Curl
JavaScript SDK
Next.js SDK
curl -X POST "https://api.astracollab.app/v1/keys" \ -H "Authorization: Bearer your-api-key-here" \ -H "Content-Type: application/json" \ -d '{ "name": "My App Key", "permissions": ["files:read", "files:write"] }'
Security Best Practices Key Naming
Use descriptive names that indicate the purpose
Include environment information (e.g., “Production App”, “Development Testing”)
Include application or service name
Permissions
Follow the principle of least privilege
Only grant necessary permissions
Use specific permissions instead of admin when possible
Regularly review and update permissions
Expiration
Set expiration dates for temporary keys
Use short expiration for testing keys
Consider rotating keys regularly
Storage
Store keys in environment variables
Never commit keys to version control
Use secure key management services
Encrypt keys at rest
Key Rotation Regularly rotate your API keys for better security:
const rotateApiKey = async ( oldKeyId ) => { // Create new key const newKey = await client . keys . create ({ name: 'Rotated Key' , permissions: [ 'files:read' , 'files:write' ] }); // Update application to use new key // ... // Revoke old key await client . keys . revoke ( oldKeyId ); };
Usage Tracking Monitor API key usage to detect unusual activity:
const key = await client . keys . get ( 'key_1234567890abcdef' ); console . log ( 'Last used:' , key . lastUsedAt ); console . log ( 'Is active:' , key . isActive );
