Credentials API

Overview

The Credentials API enables you to securely manage supplier-specific credentials for accessing PromoStandards services. Instead of relying solely on PSRESTful’s agent credentials, you can configure per-account credentials for each supplier, allowing for more flexibility and control over your PromoStandards integrations.

Why Use Custom Credentials?

PSRESTful provides agent credentials that work for most read-only operations like fetching product data, media content, and general inventory levels. However, there are critical scenarios where you need to use your own supplier credentials:

1. Customer-Specific Pricing

Suppliers provide negotiated pricing based on your account relationship. To access your customer-specific pricing through the Product Pricing & Configuration (PPC) service, you must use your own credentials. PSRESTful’s agent credentials will only return generic or list pricing.

2. Transactional Services

The following PromoStandards services require your own credentials because they involve account-specific transactions:

3. Inventory with Customer Allocation

Some suppliers provide customer-specific inventory allocations. Using your credentials ensures you see your allocated inventory, not just general availability.

Use Case: SaaS Platforms with Sub-Accounts

This feature is essential for enterprise SaaS platforms that manage multiple distributor clients through Sub-Accounts. Here’s a typical workflow:

┌─────────────────────────────────────────────────────────────────┐
│                    SaaS Platform Architecture                    │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   Your Platform (Parent Account)                                │
│   └── Sub-Account: Client A (Distributor)                       │
│       └── Credentials: Client A's supplier credentials          │
│           • SanMar credentials → Client A's pricing & orders    │
│           • HIT credentials → Client A's pricing & orders       │
│                                                                  │
│   └── Sub-Account: Client B (Distributor)                       │
│       └── Credentials: Client B's supplier credentials          │
│           • SanMar credentials → Client B's pricing & orders    │
│           • PCNA credentials → Client B's pricing & orders      │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Benefits for SaaS Platforms:

• Customer Isolation: Each sub-account has its own credentials, ensuring customers only see their own pricing and orders
• Seamless Integration: Your platform makes API calls on behalf of customers using their stored credentials
• Centralized Management: Manage all customer credentials through a single API
• No Credential Sharing: Customers don’t need to share credentials with your support team—they’re securely stored and encrypted

Key Benefits

• Per-Account Credentials: Store unique credentials for each supplier under your account
• Service-Specific Credentials: Configure different credentials for different PromoStandards services (Product, Inventory, PPC, etc.)
• Environment Separation: Maintain separate credentials for staging and production environments
• Secure Storage: All passwords are encrypted at rest and never exposed in API responses
• Audit Trail: Track who created or modified credentials and when

Getting Started

Prerequisites

• A PSRESTful account with API access
• Valid supplier credentials from your PromoStandards suppliers

Base URL

All credentials endpoints are prefixed with:

https://api.psrestful.com/extra/v2/credentials

Authentication

Option 1: API Key (Recommended for server-to-server)

X-API-Key: your-api-key-here

Option 2: OAuth2 Bearer Token

Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

Important: Public API keys are NOT supported for credentials endpoints.

API Endpoints

1. List All Credentials

Retrieve all supplier credentials configured for your account.

Endpoint:

GET /extra/v2/credentials

Example Request:

curl -X GET "https://api.psrestful.com/extra/v2/credentials" \
  -H "X-API-Key: your-api-key-here"

Response: 200 OK

{
  "count": 2,
  "results": [
    {
      "supplier_code": "SanMar",
      "supplier_name": "SanMar",
      "has_staging_credentials": true,
      "has_production_credentials": true,
      "service_credentials": [
        {
          "service": "INV",
          "environment": "PROD",
          "username": "inv_user"
        }
      ]
    },
    {
      "supplier_code": "PCNA",
      "supplier_name": "PCNA",
      "has_staging_credentials": false,
      "has_production_credentials": true,
      "service_credentials": []
    }
  ]
}

Response Fields:

Errors:

• 403 Forbidden - Not authenticated or invalid API key

2. Create or Update Supplier Credentials

Create new credentials or update existing ones for a specific supplier.

Endpoint:

POST /extra/v2/credentials

Request Body:

Example Request:

curl -X POST "https://api.psrestful.com/extra/v2/credentials" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "supplier_code": "SanMar",
    "staging_username": "my_staging_user",
    "staging_password": "my_staging_pass",
    "production_username": "my_prod_user",
    "production_password": "my_prod_pass"
  }'

Response: 201 Created

{
  "supplier_code": "SanMar",
  "supplier_name": "SanMar",
  "has_staging_credentials": true,
  "has_production_credentials": true,
  "service_credentials": []
}

Important:

• Passwords are encrypted before storage
• Passwords are never returned in API responses
• If credentials already exist for the supplier, they will be updated
• You can provide only staging OR only production credentials

Errors:

• 403 Forbidden - Not authenticated
• 404 Not Found - Supplier code not found in our system

3. Get Supplier Credentials

Retrieve credentials for a specific supplier.

Endpoint:

GET /extra/v2/credentials/{supplier_code}

Path Parameters:

Example Request:

curl -X GET "https://api.psrestful.com/extra/v2/credentials/HIT" \
  -H "X-API-Key: your-api-key-here"

Response: 200 OK

{
  "supplier_code": "HIT",
  "supplier_name": "Hit Promotional Products",
  "has_staging_credentials": true,
  "has_production_credentials": true,
  "service_credentials": [
    {
      "service": "INV",
      "environment": "PROD",
      "username": "inv_specific_user"
    },
    {
      "service": "Product",
      "environment": "PROD",
      "username": "product_user"
    }
  ]
}

Errors:

• 403 Forbidden - Not authenticated
• 404 Not Found - Credentials not found for this supplier

4. Delete Supplier Credentials

Delete all credentials for a specific supplier. This also deletes any service-specific credentials.

Endpoint:

DELETE /extra/v2/credentials/{supplier_code}

Path Parameters:

Example Request:

curl -X DELETE "https://api.psrestful.com/extra/v2/credentials/HIT" \
  -H "X-API-Key: your-api-key-here"

Response: 204 No Content

Important:

• This is a hard delete - credentials cannot be recovered
• All service-specific credentials are also deleted (cascade delete)
• After deletion, PSRESTful will fall back to default credentials (if available)

Errors:

• 403 Forbidden - Not authenticated
• 404 Not Found - Credentials not found for this supplier

5. Create or Update Service-Specific Credentials

Configure credentials for a specific PromoStandards service. This is useful when a supplier requires different credentials for different services.

Endpoint:

POST /extra/v2/credentials/{supplier_code}/services

Path Parameters:

Request Body:

Available Service Codes:

Example Request:

curl -X POST "https://api.psrestful.com/extra/v2/credentials/HIT/services" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "service": "INV",
    "environment": "PROD",
    "username": "inventory_specific_user",
    "password": "inventory_specific_pass"
  }'

Response: 201 Created

{
  "service": "INV",
  "environment": "PROD",
  "username": "inventory_specific_user"
}

Important:

• You must first create base supplier credentials before adding service-specific credentials
• Service-specific credentials override the base supplier credentials for that service/environment combination
• If the service credential already exists, it will be updated

Errors:

• 400 Bad Request - Invalid environment (must be STAGING or PROD)
• 403 Forbidden - Not authenticated
• 404 Not Found - Supplier credentials not found (create base credentials first)

6. Delete Service-Specific Credentials

Delete credentials for a specific service/environment combination.

Endpoint:

DELETE /extra/v2/credentials/{supplier_code}/services/{service}/{environment}

Path Parameters:

Example Request:

curl -X DELETE "https://api.psrestful.com/extra/v2/credentials/HIT/services/INV/PROD" \
  -H "X-API-Key: your-api-key-here"

Response: 204 No Content

Important:

• Only deletes the specific service credential
• Base supplier credentials remain intact
• After deletion, the service will use the base supplier credentials

Errors:

• 403 Forbidden - Not authenticated
• 404 Not Found - Service credential not found

Credential Resolution Hierarchy

When PSRESTful makes a PromoStandards API call, credentials are resolved in this order:

1. Request-Level Credentials - Credentials embedded in the API request (if provided)
2. Service-Specific Credentials - Credentials configured for the specific service and environment
3. Account Supplier Credentials - Base credentials configured for the supplier
4. Default Credentials - Shared credentials configured by PSRESTful (fallback)

This hierarchy allows for flexible credential management while ensuring API calls always have credentials available.

┌─────────────────────────────────────────────────────────────┐
│                    Credential Resolution                     │
├─────────────────────────────────────────────────────────────┤
│  1. Request-Level Credentials        (Highest Priority)     │
│     ↓ (if not found)                                        │
│  2. Service-Specific Credentials                            │
│     ↓ (if not found)                                        │
│  3. Account Supplier Credentials                            │
│     ↓ (if not found)                                        │
│  4. Default Credentials              (Fallback)             │
└─────────────────────────────────────────────────────────────┘

Security Features

Password Encryption

All passwords are encrypted before being stored in our database using industry-standard encryption algorithms. Passwords are never stored in plain text.

Password Privacy

Passwords are never returned in API responses. The API only indicates whether credentials are configured through boolean flags (has_staging_credentials, has_production_credentials) or returns usernames for service credentials.

Audit Trail

All credential operations are tracked with:

• created_at - Timestamp of creation
• created_by - User email who created the credentials
• modified_on - Timestamp of last modification
• modified_by - User email who last modified the credentials

Cache Invalidation

When credentials are created, updated, or deleted, the credential cache is automatically invalidated to ensure the latest credentials are used for subsequent API calls.

Complete Integration Example

Scenario: Configure Supplier Credentials for Your Account

Step 1: Create Base Supplier Credentials

# Configure production credentials for Hit Promotional Products
curl -X POST "https://api.psrestful.com/extra/v2/credentials" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "supplier_code": "HIT",
    "production_username": "your_prod_user",
    "production_password": "your_prod_pass"
  }'

Step 2: Add Service-Specific Credentials (Optional)

# HIT uses different credentials for Inventory
curl -X POST "https://api.psrestful.com/extra/v2/credentials/HIT/services" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "service": "INV",
    "environment": "PROD",
    "username": "hit_inv_user",
    "password": "hit_inv_pass"
  }'

Step 3: Verify Configuration

# Check your configured credentials
curl -X GET "https://api.psrestful.com/extra/v2/credentials/HIT" \
  -H "X-API-Key: your-api-key"

Response:

{
  "supplier_code": "HIT",
  "supplier_name": "Hit Promotional Products",
  "has_staging_credentials": false,
  "has_production_credentials": true,
  "service_credentials": [
    {
      "service": "INV",
      "environment": "PROD",
      "username": "hit_inv_user"
    }
  ]
}

Step 4: Make API Calls

Now when you make PromoStandards API calls through PSRESTful, your configured credentials will be used automatically:

# This will use your configured Inventory credentials
curl -X GET "https://api.psrestful.com/v2/suppliers/HIT/inventory/PRODUCT123?environment=PROD" \
  -H "X-API-Key: your-api-key"

Error Handling

Error Response Format

All errors return JSON with a detail field:

{
  "detail": "Error message describing what went wrong"
}

HTTP Status Codes

Common Errors and Solutions

Error: “Supplier not found”

HTTP Status: 404 Not Found

Cause: The supplier code provided does not exist in our system.

Solution:

• Verify the supplier code is correct
• Use the correct case (e.g., SanMar, HIT, PCNA)
• Check the supported suppliers list

Error: “Credentials not found”

HTTP Status: 404 Not Found

Cause: No credentials have been configured for this supplier under your account.

Solution:

• Create base credentials first using POST /extra/v2/credentials

Error: “Parent credentials must exist first”

HTTP Status: 404 Not Found

Cause: Attempting to create service-specific credentials without base supplier credentials.

Solution:

• Create base supplier credentials before adding service-specific credentials

Best Practices

1. Use Service-Specific Credentials When Needed

Some suppliers require different credentials for different services. Check with your supplier if you’re experiencing authentication issues with specific services.

2. Separate Staging and Production

Always configure separate credentials for staging and production environments when testing integrations.

3. Monitor Credential Usage

If API calls start failing with authentication errors, verify your credentials are still valid with the supplier.

4. Keep Credentials Updated

When you change passwords with a supplier, update them in PSRESTful immediately to avoid service disruptions.

5. Use Account-Level Credentials

For multi-tenant applications, use the Credentials API to manage per-customer supplier credentials, ensuring proper isolation and access control.

Frequently Asked Questions

Can I see the passwords I’ve configured?

No. For security reasons, passwords are never returned in API responses. The API only indicates whether credentials are configured.

What happens if I don’t configure credentials?

PSRESTful will fall back to default credentials if available. If no credentials are available, the API call will fail with a 403 Forbidden error.

Can I configure credentials for all suppliers at once?

No using the API. Credentials must be configured per-supplier using individual API calls. However, you can upload a CSV into our UI.

Are credentials shared across sub-accounts?

No. Each account (including sub-accounts) has its own set of credentials. Sub-accounts inherit the parent’s plan but not credentials.

How long are credentials cached?

Credentials are cached for up to 24 hours for performance. The cache is automatically invalidated when you update or delete credentials.

Related Documentation

• Sub-Accounts API - Create and manage sub-accounts for your customers
• Authentication - Learn about API authentication methods

Support

For additional help:

• Email: devs@psrestful.com

Last Updated: January 2025 API Version: v2