Skip to main content

Developers API

The Developers API allows you to manage developer accounts, generate API keys, and access developer statistics and dashboard summaries.

Authentication​

All endpoints require authentication using either:

  • API Key: Include x-api-key header
  • Cognito JWT: Include Authorization: Bearer <token> header

Base URL​

https://sdk.getjar.com/developers

Create Developer​

Create a new developer account in the GetJar platform.

Endpoint​

POST /developers

Request Body​

{
  cognitoUserId: string;      // Required: AWS Cognito user ID
  company?: string;           // Company name
  website?: string;           // Company website URL
  accountStatus?: string;     // ACTIVE, INACTIVE, SUSPENDED, BANNED
  accountTier?: string;       // FREE, BASIC, PRO, ENTERPRISE
}

Response​

{
  developerId: string;
  cognitoUserId: string;
  company: string;
  website: string;
  accountStatus: string;
  accountTier: string;
  permissions: string[];
  enabledFeatures: string[];
  createdAt: string;
  updatedAt: string;
}

Example​

import { DevelopersApi } from "@getjar-iap/sdk";

const developersApi = new DevelopersApi(configuration);

const developer = await developersApi.createDeveloper({
  createDeveloperDto: {
    cognitoUserId: "us-east-1:12345678-1234-1234-1234-123456789012",
    company: "Awesome Games Studio",
    website: "https://awesomegames.com",
    accountStatus: "ACTIVE",
    accountTier: "FREE",
  },
});

console.log("Developer ID:", developer.data.developerId);

Response Codes​

CodeDescription
201Developer created successfully
400Invalid developer data
401Unauthorized
409Developer already exists

Update Developer​

Update developer profile information.

Endpoint​

PUT /developers/:developerId

Parameters​

ParameterTypeDescription
developerIdstringThe unique developer identifier

Request Body​

{
  company?: string;
  website?: string;
  accountTier?: string;
  permissions?: string[];
  enabledFeatures?: string[];
  webhookUrl?: string;
}

Example​

const updated = await developersApi.updateDeveloper({
  developerId: "dev_123",
  updateDeveloperDto: {
    company: "Awesome Games Studio Inc.",
    accountTier: "PRO",
    webhookUrl: "https://api.example.com/webhooks",
  },
});

Response Codes​

CodeDescription
200Developer updated successfully
400Invalid update data
401Unauthorized
403Forbidden
404Developer not found

Get Developer by ID​

Retrieve detailed developer profile information.

Endpoint​

GET /developers/:developerId

Parameters​

ParameterTypeRequiredDescription
developerIdstringYesThe unique developer identifier
fieldsstringNoComma-separated list of fields to include

Example​

const developer = await developersApi.getDeveloperById({
  developerId: "dev_123",
  fields: "developerId,company,accountTier,stats",
});

console.log("Company:", developer.data.company);
console.log("Total Apps:", developer.data.stats?.totalApps);

Response Codes​

CodeDescription
200Success
401Unauthorized
404Developer not found

Get Developer by Cognito ID​

Retrieve developer profile using their AWS Cognito user ID.

Endpoint​

GET /developers/user/:cognitoUserId

Parameters​

ParameterTypeDescription
cognitoUserIdstringAWS Cognito user identifier

Example​

const developer = await developersApi.getDeveloperByCognitoId({
  cognitoUserId: "us-east-1:12345678-1234-1234-1234-123456789012",
});

console.log("Developer ID:", developer.data.developerId);

Response Codes​

CodeDescription
200Success
401Unauthorized
404Developer not found

Get Developer Summary​

Retrieve comprehensive statistics and dashboard overview.

Endpoint​

GET /developers/:developerId/summary

Response​

{
  developer: {
    developerId: string;
    company: string;
    accountTier: string;
    accountStatus: string;
  }
  stats: {
    totalApps: number;
    activeApps: number;
    totalProducts: number;
    totalRevenue: number;
    totalUsers: number;
    totalAchievements: number;
    totalLeaderboards: number;
    lastActivityAt: string;
  }
  recentActivity: Array<{
    type: string;
    description: string;
    timestamp: string;
  }>;
}

Example​

const summary = await developersApi.getDeveloperSummary({
  developerId: "dev_123",
});

console.log("Total Revenue:", summary.data.stats?.totalRevenue);
console.log("Total Users:", summary.data.stats?.totalUsers);
console.log("Recent Activity:", summary.data.recentActivity);

API Key Management​

Generate API Key​

Create a new API key with custom permissions. Important: The key will only be shown once.

Endpoint​

POST /developers/:developerId/api-keys

Request Body​

{
  name: string;           // Required: Friendly name for the key
  permissions: string[];  // Required: Array of permissions
}

Example​

const apiKey = await developersApi.generateApiKey({
  developerId: "dev_123",
  body: {
    name: "Production Server Key",
    permissions: [
      "read:achievements",
      "write:achievements",
      "read:leaderboards",
      "write:leaderboards",
    ],
  },
});

// IMPORTANT: Save this key immediately!
console.log("API Key:", apiKey.data.key);

Response Codes​

CodeDescription
201API key generated successfully
400Invalid key configuration
401Unauthorized
403Forbidden
404Developer not found

Get All API Keys​

Retrieve a list of all API keys for a developer. Actual key values are never returned.

Endpoint​

GET /developers/:developerId/api-keys

Response​

{
  keys: Array<{
    name: string;
    permissions: string[];
    createdAt: string;
    lastUsedAt: string | null;
    expiresAt: string | null;
  }>;
  total: number;
}

Example​

const keys = await developersApi.getDeveloperApiKeys({
  developerId: "dev_123",
});

console.log("Total Keys:", keys.data.total);
keys.data.keys?.forEach((key) => {
  console.log(`${key.name}: ${key.permissions?.join(", ")}`);
});

Update API Key​

Update the name or permissions of an existing API key.

Endpoint​

PUT /developers/:developerId/api-keys/:keyName

Parameters​

ParameterTypeDescription
developerIdstringDeveloper identifier
keyNamestringCurrent name of the API key

Request Body​

{
  newName?: string;       // New name for the key
  permissions?: string[]; // Updated permissions
}

Example​

const updated = await developersApi.updateApiKey({
  developerId: "dev_123",
  keyName: "Production Server Key",
  body: {
    newName: "Production API Key",
    permissions: ["read:*", "write:*"],
  },
});

Response Codes​

CodeDescription
200API key updated successfully
400Invalid update data
401Unauthorized
404API key not found

Revoke API Key​

Permanently revoke and delete an API key. This action cannot be undone.

Endpoint​

DELETE /developers/:developerId/api-keys/:keyName

Parameters​

ParameterTypeDescription
developerIdstringDeveloper identifier
keyNamestringName of the API key to revoke

Example​

await developersApi.revokeApiKey({
  developerId: "dev_123",
  keyName: "Old Development Key",
});

console.log("API key revoked successfully");

Response Codes​

CodeDescription
204API key revoked successfully
401Unauthorized
404API key not found

Common Permissions​

Here are the standard permissions available for API keys:

PermissionDescription
read:achievementsRead achievement data
write:achievementsCreate and modify achievements
read:leaderboardsRead leaderboard data
write:leaderboardsSubmit scores and manage leaderboards
read:productsRead product catalog
write:productsCreate and modify products
read:usersRead user data
write:usersModify user data
read:analyticsAccess analytics and reports
read:*Read access to all resources
write:*Write access to all resources

Complete Example​

Here's a complete workflow for setting up a new developer:

import { Configuration, DevelopersApi } from "@getjar-iap/sdk";

// Initialize SDK
const configuration = new Configuration({
  basePath: "https://sdk.getjar.com",
  apiKey: "your-api-key",
});

const developersApi = new DevelopersApi(configuration);

async function setupNewDeveloper() {
  try {
    // 1. Create developer account
    const developer = await developersApi.createDeveloper({
      createDeveloperDto: {
        cognitoUserId: "us-east-1:12345678-1234-1234-1234-123456789012",
        company: "Indie Game Studio",
        website: "https://indiegamestudio.com",
        accountStatus: "ACTIVE",
        accountTier: "FREE",
      },
    });

    const developerId = developer.data.developerId!;
    console.log("Developer created:", developerId);

    // 2. Generate production API key
    const productionKey = await developersApi.generateApiKey({
      developerId,
      body: {
        name: "Production Server",
        permissions: ["read:*", "write:*"],
      },
    });

    console.log("Production API Key:", productionKey.data.key);

    // 3. Generate development API key
    const devKey = await developersApi.generateApiKey({
      developerId,
      body: {
        name: "Development Environment",
        permissions: ["read:*", "write:achievements", "write:leaderboards"],
      },
    });

    console.log("Development API Key:", devKey.data.key);

    // 4. Get developer summary
    const summary = await developersApi.getDeveloperSummary({ developerId });
    console.log("Developer Summary:", summary.data);

    return {
      developerId,
      productionKey: productionKey.data.key,
      developmentKey: devKey.data.key,
    };
  } catch (error) {
    console.error("Error setting up developer:", error);
    throw error;
  }
}

// Run the setup
setupNewDeveloper().then((result) => {
  console.log("Setup complete!", result);
});

Error Handling​

All endpoints return standard HTTP status codes and error responses:

try {
  const developer = await developersApi.getDeveloperById({
    developerId: "invalid-id",
  });
} catch (error) {
  if (error.response) {
    console.error("Status:", error.response.status);
    console.error("Message:", error.response.data.message);
  }
}

Common error response format:

{
  statusCode: number;
  message: string;
  error?: string;
}

Best Practices​

Security​

  1. Store API keys securely: Never commit API keys to version control
  2. Use environment variables: Store keys in .env files
  3. Rotate keys regularly: Generate new keys and revoke old ones periodically
  4. Use least privilege: Grant only the permissions needed for each key
  5. Monitor key usage: Check lastUsedAt to identify unused keys

Performance​

  1. Cache developer data: Developer info changes infrequently
  2. Use field selection: Request only needed fields with the fields parameter
  3. Batch operations: Group related API calls when possible

Example: Secure Key Storage​

// .env file
GETJAR_PRODUCTION_KEY=gjk_live_abc123...
GETJAR_DEVELOPMENT_KEY=gjk_dev_xyz789...

// config.ts
import { Configuration } from '@getjar-iap/sdk';

const configuration = new Configuration({
  basePath: process.env.GETJAR_API_URL || 'https://sdk.getjar.com',
  apiKey: process.env.GETJAR_PRODUCTION_KEY
});

export default configuration;

Support​

For additional help or questions: