Getting Started with Templates

This guide walks you through setting up and using Cakewalk API integration templates for common automation workflows.

---

Prerequisites

Before you begin, ensure you have:

1. Cakewalk API Access

• Admin privileges in your Cakewalk organization

• API Key and Secret generated from the developer settings

• Access to the applications you want to manage

2. Required Information

You'll need to gather some IDs from your Cakewalk instance:

• WorkApp IDs: Unique identifiers for each application

• User IDs: Unique identifiers for users you want to manage

• Permission Level IDs: Specific permission levels for each app

3. Development Environment

• Git for version control

• Your preferred CI/CD platform (GitHub Actions, GitLab CI, etc.)

• Python 3.7+ (for Python-based templates)

• Terraform (for infrastructure templates)

---

Step 1: Get Your API Credentials

Generate API Keys

1. Log into your Cakewalk organization

2. Navigate to Settings → Developer Settings

3. Click Generate New API Key

4. Copy both the API Key and API Secret

5. Store them securely (never commit to version control)

Test Your Credentials

# Test API access
curl "https://open-api.getcakewalk.io/api/v1/Users" \
  -H "X-API-KEY: your-api-key" \
  -H "X-API-SECRET: your-api-secret"

You should receive a JSON response with user data.

---

Step 2: Gather Required IDs

Find WorkApp IDs

# List all WorkApps
curl "https://open-api.getcakewalk.io/api/v1/WorkApps" \
  -H "X-API-KEY: your-api-key" \
  -H "X-API-SECRET: your-api-secret" | jq '.data[] | {id, name}'

Find User IDs

# List all users
curl "https://open-api.getcakewalk.io/api/v1/Users" \
  -H "X-API-KEY: your-api-key" \
  -H "X-API-SECRET: your-api-secret" | jq '.data[] | {id, name, email}'

Find Permission Level IDs

# Get permission levels for a specific WorkApp
curl "https://open-api.getcakewalk.io/api/v1/WorkApps/{WORKAPP_ID}/PermissionLevels" \
  -H "X-API-KEY: your-api-key" \
  -H "X-API-SECRET: your-api-secret" | jq '.data[] | {id, name, isDefault, isPrivileged}'

---

Step 3: Choose Your Template

For New Hire Automation

• GitHub Actions: Provision Access on Hire

• Terraform: Team-based Access Management

For Auditing & Reporting

• Python Scripts: Daily Access Audit

• Python Scripts: Bulk Access Management

For Offboarding

• GitHub Actions: Offboard Employee

• CI/CD Pipelines: GitLab CI Offboarding

---

Step 4: Configure Your Template

1. Download the Template

Copy the template files to your project directory.

2. Update Configuration

Replace placeholder values with your actual IDs:

# Example: GitHub Action configuration
workapp_ids:
  github: "your-github-workapp-id"
  aws: "your-aws-workapp-id"
  slack: "your-slack-workapp-id"

3. Set Up Secrets

Configure your API credentials as secrets:

GitHub Actions:

# In your repository settings → Secrets
CAKEWALK_API_KEY: your-api-key
CAKEWALK_API_SECRET: your-api-secret

Environment Variables:

export CAKEWALK_API_KEY="your-api-key"
export CAKEWALK_API_SECRET="your-api-secret"

---

Step 5: Test Your Setup

1. Test with a Single User

Start with one test user to validate your configuration:

# Test access grant
curl -X POST "https://open-api.getcakewalk.io/api/v1/WorkApps/Accesses" \
  -H "X-API-KEY: your-api-key" \
  -H "X-API-SECRET: your-api-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [{
      "workAppId": "test-workapp-id",
      "userId": "test-user-id",
      "permissionLevelId": "test-permission-id"
    }]
  }'

2. Verify in Cakewalk UI

Check that the access was granted correctly in your Cakewalk dashboard.

3. Test Error Handling

Try with invalid IDs to ensure error handling works properly.

---

Step 6: Deploy to Production

1. Start Small

Begin with a small subset of users or applications.

2. Monitor Closely

Watch logs and monitor for any issues during initial deployment.

3. Scale Gradually

Once confident, expand to more users and applications.

4. Set Up Monitoring

Configure alerts for failed operations or unusual patterns.

---

Common Issues & Solutions

"User not found" Error

• Verify the user exists in Cakewalk

• Check email spelling and case sensitivity

• Ensure the user has been invited to your organization

"401 Unauthorized" Error

• Verify API key and secret are correct

• Check that credentials haven't expired

• Ensure proper header formatting

"Empty response" Error

• Verify the API endpoint URL

• Check network connectivity

• Review API rate limits

Permission Level Issues

• Ensure the permission level exists for the WorkApp

• Check that the permission level is active

• Verify the permission level ID is correct

---

Next Steps

Customize for Your Organization

• Adjust department mappings for your organizational structure

• Add custom validation rules

• Implement additional logging and monitoring

Advanced Features

• Set up webhook notifications

• Implement approval workflows

• Add custom reporting and analytics

Security Enhancements

• Implement IP allowlisting

• Add request signing

• Set up audit logging

---

Getting Help

Documentation

• API Reference

• Authentication Guide

• Pagination Guide

Community

• Cakewalk Community

• Template Repository

Support

• API Support

• Feature Requests