Authentication

Omise uses API keys to authenticate requests. You'll need different keys for different operations to keep your integration secure.

Overview

Omise uses HTTP Basic Authentication where your API key serves as the username and the password field is left blank. All API requests must be made over HTTPS - calls made over plain HTTP will fail.

Three Types of API Keys

1. Public Key

Used for: Client-side operations (browser, mobile app)

Format: pkey_test_... (test) or pkey_... (live)

Capabilities:

✅ Create tokens (tokenize cards)
✅ Create sources (for alternative payment methods)
✅ View tokens and sources
❌ Create charges (requires secret key)
❌ Access account information

Safe to expose: Yes, your public key can safely be included in client-side code like JavaScript, mobile apps, or HTML.

Example Usage

cURL
JavaScript
PHP

# Note the colon after the key (username:password format with empty password)
curl https://vault.omise.co/tokens \
  -X POST \
  -u pkey_test_5xp6c8ltm5wb5o45cls: \
  -d "card[name]=Somchai Prasert" \
  -d "card[number]=4242424242424242" \
  -d "card[expiration_month]=12" \
  -d "card[expiration_year]=2027" \
  -d "card[security_code]=123"

// Using Omise.js
Omise.setPublicKey('pkey_test_5xp6c8ltm5wb5o45cls');

Omise.createToken('card', {
  name: 'Somchai Prasert',
  number: '4242424242424242',
  expiration_month: 12,
  expiration_year: 2027,
  security_code: '123'
}, function(statusCode, response) {
  console.log(response);
});

<?php
define('OMISE_PUBLIC_KEY', 'pkey_test_5xp6c8ltm5wb5o45cls');

$token = OmiseToken::create([
  'card' => [
    'name' => 'Somchai Prasert',
    'number' => '4242424242424242',
    'expiration_month' => 12,
    'expiration_year' => 2027,
    'security_code' => '123'
  ]
]);
?>

Why Use Public Keys?

Public keys let you tokenize sensitive data on the client side, so card information never touches your servers. This significantly reduces your PCI compliance requirements.

2. Secret Key

Used for: Server-side operations

Format: skey_test_... (test) or skey_... (live)

Capabilities:

✅ Create charges
✅ Create refunds
✅ Manage customers
✅ Create and manage transfers
✅ Access all account information
✅ Perform all operations

Safe to expose: NO! Secret keys must be kept confidential and only used server-side.

Example Usage

cURL
Node.js
Python
Ruby
PHP

curl https://api.omise.co/charges \
  -X POST \
  -u skey_test_5xp6c8n0jvds5mmjizz: \
  -d "amount=100000" \
  -d "currency=thb" \
  -d "card=tokn_test_5xp6ca4dtzx5cskm9mk"

const omise = require('omise')({
  secretKey: 'skey_test_5xp6c8n0jvds5mmjizz'
});

omise.charges.create({
  amount: 100000,
  currency: 'thb',
  card: 'tokn_test_5xp6ca4dtzx5cskm9mk'
}, function(err, charge) {
  console.log(charge);
});

import omise

omise.api_secret = 'skey_test_5xp6c8n0jvds5mmjizz'

charge = omise.Charge.create(
    amount=100000,
    currency='thb',
    card='tokn_test_5xp6ca4dtzx5cskm9mk'
)

require 'omise'

Omise.secret_api_key = 'skey_test_5xp6c8n0jvds5mmjizz'

charge = Omise::Charge.create(
  amount: 100000,
  currency: 'thb',
  card: 'tokn_test_5xp6ca4dtzx5cskm9mk'
)

<?php
define('OMISE_SECRET_KEY', 'skey_test_5xp6c8n0jvds5mmjizz');

$charge = OmiseCharge::create([
  'amount' => 100000,
  'currency' => 'thb',
  'card' => 'tokn_test_5xp6ca4dtzx5cskm9mk'
]);
?>

Keep Secret Keys Secret

Never commit secret keys to version control, expose them in client-side code, or share them publicly. Always use environment variables or secure configuration management.

3. Chain Key

Used for: Sub-merchant operations (if you're building a marketplace/platform)

Format: ck_test_... (test) or ck_... (live)

Capabilities:

✅ Make requests on behalf of connected sub-merchants
✅ All capabilities of secret key for sub-accounts

Safe to expose: NO! Treat chain keys with the same security as secret keys.

Chain keys are only relevant if you're using Omise Connect to manage sub-merchant accounts. Most merchants won't need chain keys.

Test vs Live Keys

Each key type has both test and live versions:

Environment	Public Key Prefix	Secret Key Prefix	Purpose
Test	`pkey_test_`	`skey_test_`	Development & testing
Live	`pkey_`	`skey_`	Production transactions

Automatic Environment Detection

Test keys only work in test mode and live keys only work in live mode. This prevents accidental charges during development.

Where to Find Your Keys

Log into your Omise Dashboard
Navigate to Settings → Keys
You'll see your keys for both test and live environments

Test Keys

Test keys are available immediately after signup - no verification required!

Live Keys

Live keys become available after you complete your business verification. See the Going Live guide for details.

How to Use API Keys

HTTP Basic Authentication

Omise uses HTTP Basic Authentication where:

Username: Your API key
Password: Empty (leave blank)

The authentication header format is:

Authorization: Basic base64(api_key:)

Note the colon after the API key - the password field is intentionally left empty.

In Code Examples

cURL
Node.js
Python
Ruby
PHP

# Public key - creates token
curl https://vault.omise.co/tokens \
  -u pkey_test_YOUR_KEY:

# Secret key - creates charge
curl https://api.omise.co/charges \
  -u skey_test_YOUR_KEY:

// Initialize with secret key
const omise = require('omise')({
  secretKey: 'skey_test_YOUR_KEY'
});

// Public key is set differently (for Omise.js in browser)
Omise.setPublicKey('pkey_test_YOUR_KEY');

import omise

# Set keys
omise.api_public = 'pkey_test_YOUR_KEY'
omise.api_secret = 'skey_test_YOUR_KEY'

# Keys are used automatically based on the operation

require 'omise'

# Set keys
Omise.api_key = 'pkey_test_YOUR_KEY'  # Public operations
Omise.secret_api_key = 'skey_test_YOUR_KEY'  # Secret operations

<?php
// Define keys as constants
define('OMISE_PUBLIC_KEY', 'pkey_test_YOUR_KEY');
define('OMISE_SECRET_KEY', 'skey_test_YOUR_KEY');

// Library uses them automatically
?>

Security Best Practices

DO ✅

Use Environment Variables

# .env file
OMISE_PUBLIC_KEY=pkey_test_...
OMISE_SECRET_KEY=skey_test_...

Store Keys Securely
- Use secrets management services (AWS Secrets Manager, Azure Key Vault, etc.)
- Use environment variables on your server
- Encrypt keys in your configuration
Rotate Keys Regularly
- You can generate new keys in your dashboard
- Old keys remain valid until you delete them
- Update your code gradually to avoid downtime
Use Different Keys for Different Environments
- Development: Test keys
- Staging: Test keys
- Production: Live keys
Monitor Key Usage
- Check your dashboard for unauthorized API calls
- Set up alerts for unusual activity

DON'T ❌

Never Commit Keys to Version Control

# Add to .gitignore
.env
.env.local
config/secrets.yml

Never Expose Secret Keys Client-Side

// ❌ WRONG - Secret key in JavaScript
const omise = require('omise')({
  secretKey: 'skey_test_...'  // Visible to users!
});

Never Share Keys Publicly
- Don't post keys in support tickets
- Don't share keys via email or chat
- Don't include keys in screenshots

Never Hard-Code Keys

// ❌ WRONG
define('OMISE_SECRET_KEY', 'skey_test_5xp...');

// ✅ CORRECT
define('OMISE_SECRET_KEY', getenv('OMISE_SECRET_KEY'));

Authentication Errors

Invalid Key

{
  "object": "error",
  "location": "https://www.omise.co/api-errors#authentication-failure",
  "code": "authentication_failure",
  "message": "authentication failed"
}

Causes:

Using the wrong key type (public vs secret)
Typo in the API key
Using a deleted key
Key doesn't match the environment (test vs live)

Solution: Double-check your key in the dashboard and ensure you're using the correct key type.

Missing Authentication

{
  "object": "error",
  "location": "https://www.omise.co/api-errors#authentication-required",
  "code": "authentication_required",
  "message": "authentication required"
}

Cause: No API key provided in the request.

Solution: Ensure your HTTP client is configured to send Basic Authentication headers.

Key Management

Generating New Keys

Go to Settings → Keys in your dashboard
Click Generate New Key
Choose the key type (Public or Secret)
Copy the new key immediately (you can't retrieve it later)
Update your application code
Test thoroughly before deleting old keys

Deleting Keys

Generate and deploy new keys first
Ensure all services are using the new keys
Delete the old keys from your dashboard
Monitor for any authentication errors

Key Deletion

Deleting a key immediately invalidates it. Make sure no services are still using a key before deletion!

FAQ

Can I use my secret key in mobile apps?

No! Mobile app code can be decompiled, exposing your secret key. Always:

Use your public key in mobile apps
Send tokens to your server
Create charges server-side with your secret key

See our mobile SDK guides for proper implementation.

How do I switch from test to live mode?

Simply replace your test keys with live keys in your code:

// Change from:
const omise = require('omise')({
  secretKey: 'skey_test_...'
});

// To:
const omise = require('omise')({
  secretKey: 'skey_...'  // No "_test_" prefix
});

Your integration code remains exactly the same!

What if my keys are compromised?

Immediately: Generate new keys in your dashboard
Delete the compromised keys
Update all your services with new keys
Monitor your account for unauthorized charges
Contact support@omise.co to report the incident

We recommend rotating keys as a precaution if:

A developer with key access leaves your company
You suspect a security breach
Keys were accidentally committed to public repositories

Can I have multiple sets of keys?

Each account has one set of test keys and one set of live keys. However, you can:

Regenerate keys at any time (old keys remain valid)
Create multiple Omise accounts for different brands/businesses
Use sub-accounts with Omise Connect (for platforms)

Do keys expire?

No, API keys don't expire automatically. However, we recommend:

Rotating keys periodically (every 6-12 months)
Generating new keys when team members with access leave
Immediately replacing keys if compromised

What's the difference between vault.omise.co and api.omise.co?

vault.omise.co: Used with public keys for tokenization (keeping card data secure)
api.omise.co: Used with secret keys for all other operations

This separation ensures sensitive card data never reaches your servers or the main API.

Quickstart Guide - Make your first API call
Security Best Practices - Complete security guide
Test Mode - Testing with test keys
Going Live - Get your live keys

Questions? Contact support@omise.co or check the API Reference for detailed endpoint documentation.

Overview​

Three Types of API Keys​

1. Public Key​

Example Usage​

2. Secret Key​

Example Usage​

3. Chain Key​

Test vs Live Keys​

Where to Find Your Keys​

Test Keys​

Live Keys​

How to Use API Keys​

HTTP Basic Authentication​

In Code Examples​

Security Best Practices​

DO ✅​

DON'T ❌​

Authentication Errors​

Invalid Key​

Missing Authentication​

Key Management​

Generating New Keys​

Deleting Keys​

FAQ​

Related Resources​

Overview

Three Types of API Keys

1. Public Key

Example Usage

2. Secret Key

Example Usage

3. Chain Key

Test vs Live Keys

Where to Find Your Keys

Test Keys

Live Keys

How to Use API Keys

HTTP Basic Authentication

In Code Examples

Security Best Practices

DO ✅

DON'T ❌

Authentication Errors

Invalid Key

Missing Authentication

Key Management

Generating New Keys

Deleting Keys

FAQ

Related Resources