Version: 2019-05-29 (Current)

Authentication

Omise uses HTTP Basic Authentication with API keys. Learn how to securely authenticate your requests and choose the right key for each operation.

Overview

Every Omise API request must be authenticated using one of your API keys. Omise provides different key types for different purposes, each with specific access permissions and security requirements.

Quick Start

Public Key (pkey_*) → Client-side code, creates tokens/sources only
Secret Key (skey_*) → Server-side code, full API access
Never expose your secret key in client-side code or public repositories

API Keys

Key Types

Omise provides three types of API keys:

Key Type	Format	Used For	Where to Use	Access Level
Public Key	`pkey_test_` / `pkey_live_`	Tokenizing cards, creating sources	Client-side (browser, mobile app)	Limited - can only create tokens & sources
Secret Key	`skey_test_` / `skey_live_`	Charges, customers, refunds, all operations	Server-side only	Full API access
Chain Key	`chain_*`	Parent account operations on sub-merchants	Server-side only	Sub-merchant management

Test vs Live Keys

Each key type comes in test and live versions:

Test Keys (Development)

Contain _test_ in the key string
Example: skey_test_5xuy4w91xqz7d1w9u0t
✅ Safe for development and testing
✅ Accept test card numbers
✅ Don't process real money
✅ Trigger test webhooks

Live Keys (Production)

Don't contain _test_
Example: skey_live_5xuy4w91xqz7d1w9u0t
⚠️ Process real payments
⚠️ Charge real cards
⚠️ Must be kept secure

Security Critical

Never commit live keys to version control. Use environment variables and secure secret management systems.

Finding Your API Keys

Log in to the Omise Dashboard
Navigate to Settings → Keys
Copy your test keys for development
Copy your live keys when ready for production

You can generate new keys and revoke compromised keys from this page.

How Authentication Works

Omise uses HTTP Basic Authentication:

Username: Your API key
Password: Leave blank (empty string)

The API key is sent in the Authorization header as a Base64-encoded string:

Authorization: Basic <base64(api_key:)>

Note the Colon

The API key must be followed by a colon (:) when encoding, even though the password is empty.

Authentication Examples

Using cURL

# Using secret key
curl https://api.omise.co/account \
  -u skey_test_5xuy4w91xqz7d1w9u0t:

# Using public key
curl https://vault.omise.co/tokens \
  -X POST \
  -u pkey_test_5xuy4w91xqz7d1w9u0t: \
  -d "card[name]=John Doe" \
  -d "card[number]=4242424242424242" \
  -d "card[expiration_month]=12" \
  -d "card[expiration_year]=2027" \
  -d "card[security_code]=123"

Using Ruby

require 'omise'

# Set your secret key
Omise.api_key = 'skey_test_5xuy4w91xqz7d1w9u0t'

# Make authenticated requests
account = Omise::Account.retrieve

# Using public key for tokens
Omise.vault_api_key = 'pkey_test_5xuy4w91xqz7d1w9u0t'
token = Omise::Token.create({
  card: {
    name: 'John Doe',
    number: '4242424242424242',
    expiration_month: 12,
    expiration_year: 2027,
    security_code: '123'
  }
})

Using Python

import omise

# Set your secret key
omise.api_secret = 'skey_test_5xuy4w91xqz7d1w9u0t'

# Make authenticated requests
account = omise.Account.retrieve()

# Using public key for tokens
omise.api_public = 'pkey_test_5xuy4w91xqz7d1w9u0t'
token = omise.Token.create(
    name='John Doe',
    number='4242424242424242',
    expiration_month=12,
    expiration_year=2027,
    security_code='123'
)

Using PHP

<?php
require_once 'vendor/autoload.php';

// Set your secret key
define('OMISE_SECRET_KEY', 'skey_test_5xuy4w91xqz7d1w9u0t');
define('OMISE_PUBLIC_KEY', 'pkey_test_5xuy4w91xqz7d1w9u0t');

// Make authenticated requests
$account = OmiseAccount::retrieve();

// Using public key for tokens
$token = OmiseToken::create(array(
    'card' => array(
        'name' => 'John Doe',
        'number' => '4242424242424242',
        'expiration_month' => 12,
        'expiration_year' => 2027,
        'security_code' => '123'
    )
));

Using Node.js

const omise = require('omise')({
  secretKey: 'skey_test_5xuy4w91xqz7d1w9u0t',
  publicKey: 'pkey_test_5xuy4w91xqz7d1w9u0t'
});

// Make authenticated requests
const account = await omise.account.retrieve();

// Using public key for tokens
const token = await omise.tokens.create({
  card: {
    name: 'John Doe',
    number: '4242424242424242',
    expiration_month: 12,
    expiration_year: 2027,
    security_code: '123'
  }
});

Using Go

package main

import (
    "github.com/omise/omise-go"
    "github.com/omise/omise-go/operations"
)

func main() {
    client, _ := omise.NewClient(
        "pkey_test_5xuy4w91xqz7d1w9u0t",
        "skey_test_5xuy4w91xqz7d1w9u0t",
    )

    // Make authenticated requests
    account, _ := client.Account()

    // Using public key for tokens
    token, _ := client.CreateToken(&operations.CreateToken{
        Name:            "John Doe",
        Number:          "4242424242424242",
        ExpirationMonth: 12,
        ExpirationYear:  2027,
        SecurityCode:    "123",
    })
}

Which Key to Use

Use Public Key For:

✅ Client-Side Operations (Browser, Mobile App)

Creating tokens from card data
Creating sources for alternative payment methods
Any operation that handles sensitive card information

Why? The public key is safe to embed in client-side code because it can only create tokens and sources - it cannot charge cards or access sensitive account data.

// ✅ Safe - Public key in client-side JavaScript
Omise.setPublicKey('pkey_test_5xuy4w91xqz7d1w9u0t');
Omise.createToken('card', cardData, function(status, response) {
  // Send token to server
});

Use Secret Key For:

✅ Server-Side Operations Only

Creating charges
Managing customers
Processing refunds
Creating transfers
Accessing account information
Any operation involving money or sensitive data

Why? The secret key has full API access and must never be exposed.

# ✅ Safe - Secret key on server only
Omise.api_key = ENV['OMISE_SECRET_KEY']
charge = Omise::Charge.create({
  amount: 100000,
  currency: 'thb',
  card: params[:omise_token]
})

❌ Never Do This:

<!-- ❌ DANGEROUS - Secret key exposed in HTML -->
<script>
  const secretKey = 'skey_live_5xuy4w91xqz7d1w9u0t';
</script>

// ❌ DANGEROUS - Secret key in client-side code
fetch('https://api.omise.co/charges', {
  headers: {
    'Authorization': 'Basic ' + btoa('skey_live_...:')
  }
});

Security Best Practices

1. Store Keys Securely

✅ Good: Environment Variables

# .env file (DO NOT commit to git)
OMISE_PUBLIC_KEY=pkey_test_5xuy4w91xqz7d1w9u0t
OMISE_SECRET_KEY=skey_test_5xuy4w91xqz7d1w9u0t

# Access in your code
Omise.api_key = ENV['OMISE_SECRET_KEY']

✅ Good: Secret Management Systems

AWS Secrets Manager
Google Cloud Secret Manager
Azure Key Vault
HashiCorp Vault

❌ Bad: Hardcoded Keys

# ❌ NEVER hardcode keys
Omise.api_key = 'skey_test_5xuy4w91xqz7d1w9u0t'

2. Separate Test and Production

# Development environment
OMISE_SECRET_KEY=skey_test_...

# Production environment
OMISE_SECRET_KEY=skey_live_...

3. Rotate Keys Regularly

If you suspect a key has been compromised:

Generate a new key in the Dashboard
Update your application with the new key
Test thoroughly
Revoke the old key

4. Restrict Key Permissions

While Omise doesn't support granular key permissions yet, follow the principle of least privilege:

Use public keys wherever possible
Keep secret keys on secure servers only
Never share keys between team members (each should have their own dashboard account)

5. Monitor Key Usage

Check Dashboard logs regularly
Set up alerts for unusual activity
Monitor failed authentication attempts

Authentication Errors

401 Unauthorized

Cause: Invalid or missing API key

{
  "object": "error",
  "code": "authentication_failure",
  "message": "authentication failed"
}

Solutions:

✅ Check that your API key is correct
✅ Ensure the key hasn't been revoked
✅ Verify you're using the right key for the operation
✅ Check for extra spaces or characters in the key

403 Forbidden

Cause: Key is valid but lacks permission for this operation

{
  "object": "error",
  "code": "forbidden",
  "message": "key has insufficient permissions"
}

Solutions:

✅ Use secret key instead of public key
✅ Check if your account has access to this feature
✅ Verify key hasn't been restricted

API Versioning

Specify the API version in requests using the Omise-Version header:

curl https://api.omise.co/charges \
  -u skey_test_5xuy4w91xqz7d1w9u0t: \
  -H "Omise-Version: 2019-05-29"

If not specified, requests use your account's default API version (set in Dashboard).

Learn more about API Versioning →

Testing Authentication

Test with Account Endpoint

The simplest way to test your authentication:

# Test secret key
curl https://api.omise.co/account \
  -u skey_test_5xuy4w91xqz7d1w9u0t:

# Test public key (should fail - public keys can't access /account)
curl https://api.omise.co/account \
  -u pkey_test_5xuy4w91xqz7d1w9u0t:

Expected Response (Secret Key):

{
  "object": "account",
  "id": "acct_5xuy4w91xqz7d1w9u0t",
  "email": "merchant@example.com",
  "created_at": "2027-01-01T00:00:00Z",
  ...
}

Expected Response (Public Key):

{
  "object": "error",
  "code": "authentication_failure",
  "message": "authentication failed"
}

FAQ

Can I use the same key for multiple applications?

Yes, but it's not recommended for production. While technically possible, using separate keys for different applications helps with:

Security (revoke one key without affecting others)
Monitoring (track usage per application)
Debugging (identify which app has issues)

Consider using sub-merchant accounts for completely separate applications.

What happens if my secret key is compromised?

Immediately generate a new secret key in the Dashboard
Update your application with the new key
Revoke the compromised key
Monitor your account for unauthorized charges
Contact support@omise.co if you see suspicious activity

Can I regenerate keys without downtime?

Yes! Omise allows you to have multiple active keys simultaneously:

Generate a new key
Deploy your application with the new key
Verify the new key works
Revoke the old key

This allows zero-downtime key rotation.

Do API keys expire?

No, Omise API keys don't expire automatically. However, you should:

Rotate keys regularly (every 6-12 months)
Revoke unused keys
Generate new keys after team member departures

Can I restrict API key permissions?

Currently, Omise has two permission levels:

Public keys - Limited to token/source creation
Secret keys - Full API access

Granular permission controls are not yet available. Use separate sub-merchant accounts for isolation.

Quick Reference

Authentication Checklist

Before going live, verify:

Key Format Reference

Public Test:    pkey_test_XXXXXXXXXXXXXXXXXXXX
Public Live:    pkey_live_XXXXXXXXXXXXXXXXXXXX
Secret Test:    skey_test_XXXXXXXXXXXXXXXXXXXX
Secret Live:    skey_live_XXXXXXXXXXXXXXXXXXXX
Chain:          chain_XXXXXXXXXXXXXXXXXXXX

Next: Learn about Error Handling to gracefully handle API failures.

Overview​

API Keys​

Key Types​

Test vs Live Keys​

Test Keys (Development)​

Live Keys (Production)​

Finding Your API Keys​

How Authentication Works​

Authentication Examples​

Using cURL​

Using Ruby​

Using Python​

Using PHP​

Using Node.js​

Using Go​

Which Key to Use​

Use Public Key For:​

Use Secret Key For:​

❌ Never Do This:​

Security Best Practices​

1. Store Keys Securely​

✅ Good: Environment Variables​

✅ Good: Secret Management Systems​

❌ Bad: Hardcoded Keys​

2. Separate Test and Production​

3. Rotate Keys Regularly​

4. Restrict Key Permissions​

5. Monitor Key Usage​

Authentication Errors​

401 Unauthorized​

403 Forbidden​

API Versioning​

Testing Authentication​

Test with Account Endpoint​

FAQ​

Quick Reference​

Authentication Checklist​

Key Format Reference​

Related Resources​