P
PUGUH
EN Get Started

Autentikasi API

Pelajari cara autentikasi dengan API ARSAKA PUGUH.

Metode Autentikasi

PUGUH mendukung dua metode autentikasi:

  1. API Keys: Untuk integrasi server-to-server (gunakan header X-API-Key)
  2. JWT Tokens: Untuk operasi konteks pengguna (gunakan header Authorization: Bearer)

API Keys

Mendapatkan API Key

  1. Buka pengaturan profil Anda
  2. Klik "API Keys"
  3. Klik "Create New Key"
  4. Salin key (hanya ditampilkan sekali!)

Atau buat service account untuk penggunaan produksi.

Menggunakan API Keys

Sertakan key di header X-API-Key:

bash 
curl -X GET https://api-puguh.arsaka.io/api/v1/organizations \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Organization-ID: YOUR_ORGANIZATION_ID"

Header yang Diperlukan

HeaderWajibDeskripsi
X-API-Key Ya API key Anda
X-Organization-ID Ya UUID organisasi Anda
X-Application-ID Terkadang Diperlukan untuk operasi berskala aplikasi
Content-Type Untuk POST/PUT Biasanya application/json

JWT Tokens

Login

Autentikasi dengan email dan password untuk mendapatkan pasangan token JWT:

bash 
curl -X POST https://api-puguh.arsaka.io/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your_password"
  }'

Response (dikembalikan langsung, tanpa wrapper):

json 
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBhIHJlZnJl..."
}

JWT tokens ditandatangani dengan RS256 (asimetris). Anda dapat memverifikasi token secara lokal menggunakan public key dari endpoint JWKS:

bash 
curl -X GET https://api-puguh.arsaka.io/.well-known/jwks.json

Register

Buat akun pengguna baru:

bash 
curl -X POST https://api-puguh.arsaka.io/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@example.com",
    "password": "secure_password",
    "full_name": "Jane Doe"
  }'

Response:

json 
{
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "newuser@example.com",
  "organization_id": "660e8400-e29b-41d4-a716-446655440000"
}

Menggunakan JWT Tokens

Sertakan access token di header Authorization:

bash 
curl -X GET https://api-puguh.arsaka.io/api/v1/organizations \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Memperbarui Token

Sebelum access token kedaluwarsa, gunakan refresh token untuk mendapatkan yang baru:

bash 
curl -X POST https://api-puguh.arsaka.io/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "dGhpcyBpcyBhIHJlZnJl..."
  }'

Response:

json 
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Autentikasi SDK

JavaScript / TypeScript

typescript 
import { PuguhClient } from '@arsaka/puguh-sdk';

// Using API Key
const client = new PuguhClient({
  apiKey: process.env.PUGUH_API_KEY,
  organizationId: process.env.PUGUH_ORGANIZATION_ID,
});

// Using JWT
const client = new PuguhClient({
  accessToken: userToken,
  onTokenExpired: async () => {
    const newToken = await refreshToken();
    return newToken;
  },
});

Python

python 
from puguh_sdk import PuguhClient

# Using API Key
client = PuguhClient(
    api_key=os.environ['PUGUH_API_KEY'],
    organization_id=os.environ['PUGUH_ORGANIZATION_ID']
)

# Using JWT
client = PuguhClient(
    access_token=user_token,
    on_token_expired=refresh_token_callback
)

Praktik Keamanan Terbaik

Keamanan API Key

  1. Jangan pernah commit key ke source control
    bash 
    # .gitignore
.env
*.key
  2. Gunakan environment variables
    bash 
    export PUGUH_API_KEY=your_key_here
  3. Rotasi key secara berkala
    • Rotasi key produksi setiap kuartal
    • Rotasi segera jika terkompromi
  4. Gunakan key terpisah per environment
    • Key development
    • Key staging
    • Key production

Keamanan Token

  1. Simpan dengan aman
    • Gunakan secure cookies (HttpOnly, Secure, SameSite)
    • Jangan simpan di localStorage untuk aplikasi sensitif
  2. Masa berlaku singkat
    • Access tokens: disarankan 1 jam
    • Refresh tokens: 7-30 hari
  3. Revoke saat logout
    bash 
    curl -X POST https://api-puguh.arsaka.io/api/v1/auth/logout \
  -H "Authorization: Bearer YOUR_TOKEN"

Response Error

PUGUH menggunakan kode status HTTP standar. Response error mengikuti format FastAPI:

401 Unauthorized

Kredensial tidak ada atau tidak valid:

json 
{
  "detail": "Invalid or expired token"
}

403 Forbidden

Kredensial valid tetapi tidak memiliki izin:

json 
{
  "detail": "Missing permission: organization.members.create"
}

422 Validation Error

Body request gagal validasi:

json 
{
  "detail": [
    {
      "loc": ["body", "email"],
      "msg": "value is not a valid email address",
      "type": "value_error.email"
    }
  ]
}

429 Too Many Requests

json 
{
  "detail": "Rate limit exceeded. Retry after 60 seconds."
}

Periksa header Retry-After untuk waktu tunggu dalam detik.

Rate Limiting

Panggilan API dibatasi per paket:

PaketRequest/menit
Free60
Pro300
Business1.000
EnterpriseKustom

Header rate limit disertakan di setiap response:

http 
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299
X-RateLimit-Reset: 1640000000
Retry-After: 60

Menguji Autentikasi

Uji API Key

Verifikasi API key Anda berfungsi dengan memanggil endpoint health:

bash 
curl -X GET https://api-puguh.arsaka.io/api/v1/health \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Organization-ID: YOUR_ORGANIZATION_ID"

Uji JWT Token

Login dan gunakan token yang dikembalikan untuk memanggil endpoint yang dilindungi:

bash 
# 1. Login to get a token
TOKEN=$(curl -s -X POST https://api-puguh.arsaka.io/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "your_password"}' \
  | jq -r '.access_token')

# 2. Use the token
curl -X GET https://api-puguh.arsaka.io/api/v1/iam/users \
  -H "Authorization: Bearer $TOKEN"

Integrasi OAuth (Enterprise)

Untuk integrasi SSO:

URL Otorisasi

http 
https://api-puguh.arsaka.io/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=YOUR_REDIRECT_URI
  &response_type=code
  &scope=read:user read:resources
  &state=RANDOM_STATE

Tukar Code dengan Token

bash 
curl -X POST https://api-puguh.arsaka.io/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "redirect_uri=YOUR_REDIRECT_URI"

Terkait