---
title: "API Key"
description: "Cách lấy HMAC secret hoặc tạo cặp khóa client Ed25519 dùng để ký các yêu cầu API, bằng OpenSSL hoặc AWS KMS."
url: https://docs.fystack.io/vi/api-keys
last_updated: 2026-11-13
---

> ## Documentation index
> Fetch the complete documentation index at: https://docs.fystack.io/llms.txt
> Use it to discover all available pages before exploring further.

# API Key

API key của Fystack sử dụng HMAC secret hoặc cặp khóa client Ed25519 để ký yêu cầu. Trang này hướng dẫn cách lấy đúng vật liệu khóa cho từng lược đồ ký. Xem [Xác thực API](https://docs.fystack.io/authentication.md) để biết cách hoạt động của việc ký.

> **Info.** Nên ưu tiên lược đồ **Client Key Pair** (Ed25519) cho mọi mục đích ngoài việc thử nghiệm nhanh. HMAC secret là một thông tin xác thực dạng văn bản thuần mà ứng dụng của bạn phải lưu giữ, trong khi khóa riêng tư Ed25519 có thể nằm trong HSM hoặc AWS KMS và hoàn toàn không cần xuất ra ngoài, xem [Client Key Pair](#client-key-pair) bên dưới.

---

## HMAC Secret

Bạn không cần tạo khóa. Khi bạn tạo API key từ dashboard mà không đăng ký khóa công khai, Fystack sẽ tạo secret cho bạn và chỉ hiển thị một lần, dưới dạng chuỗi mã hóa hex. Cách này dễ thiết lập hơn cặp khóa client, nhưng secret là thông tin xác thực dạng văn bản thuần mà ứng dụng của bạn phải lưu giữ, hãy ưu tiên [Client Key Pair](#client-key-pair) bên dưới khi có thể.

> **Warning.** Sao chép `api_secret` ngay lập tức và lưu trữ an toàn, nó không thể được lấy lại sau khi tạo. Nếu bị mất, hãy xóa key và tạo key mới.

```typescript
import { FystackSDK, Environment } from '@fystack/sdk'

const sdk = new FystackSDK({
  credentials: {
    apiKey: 'YOUR_API_KEY',
    apiSecret: 'YOUR_API_SECRET'
  },
  workspaceId: 'YOUR_WORKSPACE_ID',
  environment: Environment.Production
})
```

---

## Client Key Pair

Với lược đồ Ed25519, khóa riêng tư không bao giờ rời khỏi tiến trình của bạn, chỉ có khóa công khai PEM tương ứng được đăng ký với Fystack khi bạn tạo API key từ dashboard. Hãy tạo cặp khóa bằng công cụ phù hợp với hệ thống của bạn, sau đó dán khóa công khai vào dashboard.

_Image: Hộp thoại Create API Key với Client Key Pair được chọn làm phương thức xác thực khuyến nghị, sử dụng khóa công khai Ed25519 và không lưu secret_

> **Info.** Với môi trường production, hãy tạo khóa trong kho lưu trữ có phần cứng bảo vệ như AWS KMS hoặc HSM on-prem thay vì dưới dạng tệp PEM. Khi đó khóa riêng tư không thể xuất ra, không bao giờ chạm vào bộ nhớ ứng dụng hay ổ đĩa, và không thể bị đánh cắp ngay cả khi máy chủ bị xâm nhập. Sử dụng `AwsKmsSigner` (bên dưới) cho trường hợp này, chỉ dùng `LocalPrivateKeySigner` và tệp PEM cho phát triển và kiểm thử cục bộ.

### Sử dụng SDK

Nếu bạn dùng `@fystack/sdk`, hãy truyền một `signer` vào `credentials` thay vì khóa thô, SDK sẽ tự xây dựng chuỗi chuẩn hóa và ký từng yêu cầu cho bạn. Sử dụng `LocalPrivateKeySigner` cho khóa PEM trong tiến trình, hoặc `AwsKmsSigner` khi khóa riêng tư nằm trong AWS KMS:

```typescript
import { FystackSDK, LocalPrivateKeySigner, Environment } from '@fystack/sdk'

const sdk = new FystackSDK({
  credentials: {
    apiKey: 'YOUR_API_KEY',
    signer: new LocalPrivateKeySigner('-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----')
  },
  workspaceId: 'YOUR_WORKSPACE_ID',
  environment: Environment.Production
})
```

`AwsKmsSigner` yêu cầu cài đặt `@aws-sdk/client-kms` (được tải lười), hoặc truyền một client đã cấu hình sẵn qua `client` thay vì `clientConfig`. `clientConfig` được truyền trực tiếp vào `new KMSClient(...)`, vì vậy nó khác nhau giữa phát triển cục bộ với LocalStack/ministack và môi trường production:

```typescript
import { FystackSDK, AwsKmsSigner, Environment } from '@fystack/sdk'

const sdk = new FystackSDK({
  credentials: {
    apiKey: API_KEY,
    signer: new AwsKmsSigner({
      keyId: 'alias/signer',
      clientConfig: {
        region: 'ap-southeast-1',
        endpoint: 'http://localhost:4566',
        credentials: { accessKeyId: 'test', secretAccessKey: 'test' }
      }
    })
  },
  environment: Environment.Production,
  debug: true
})
```

```typescript
import { FystackSDK, AwsKmsSigner, Environment } from '@fystack/sdk'

const sdk = new FystackSDK({
  credentials: {
    apiKey: API_KEY,
    // Drop endpoint and credentials, the KMS client picks up the
    // task/instance IAM role and the real region automatically.
    signer: new AwsKmsSigner({
      keyId: 'alias/signer',
      clientConfig: { region: 'ap-southeast-1' }
    })
  },
  environment: Environment.Production,
  debug: true
})
```

> **Warning.** Không bao giờ hardcode `accessKeyId` / `secretAccessKey` trong production, cặp giá trị trong ví dụ LocalStack là thông tin xác thực cố định chỉ dùng cục bộ. Hãy để IAM role của môi trường runtime cung cấp thông tin xác thực.

Không dùng Node.js? Xem [Ký Ed25519](https://docs.fystack.io/authentication.md#ed25519-signing) để ký trực tiếp chuỗi chuẩn hóa, với cả khóa PEM cục bộ và AWS KMS, bằng Go, Python, PHP và Java.

### Tạo cặp khóa bằng OpenSSL

```bash
openssl genpkey -algorithm ed25519 -out private.pem
openssl pkey -in private.pem -pubout -out public.pem
```

Dán nội dung của `public.pem` vào dashboard khi tạo API key, và giữ `private.pem` để ký, truyền nó vào SDK dưới dạng `new LocalPrivateKeySigner(privateKeyPem)`.

### Tạo cặp khóa bằng AWS KMS

AWS KMS hỗ trợ Ed25519 làm khóa ký bất đối xứng (`ECC_NIST_EDWARDS25519`). Tạo khóa, sau đó xuất phần khóa công khai:

```bash
KEY_ID=$(awslocal kms create-key \
  --key-spec ECC_NIST_EDWARDS25519 --key-usage SIGN_VERIFY \
  --query KeyMetadata.KeyId --output text)
echo "$KEY_ID"
```

`get-public-key` đã trả về khóa dưới dạng DER mã hóa base64 (`SubjectPublicKeyInfo`), chính là nội dung mà một khóa công khai PEM bao bọc, nên không cần chuyển qua `openssl` để định dạng lại. Chỉ cần bọc kết quả base64 bằng các header PEM:

```bash
{
  echo "-----BEGIN PUBLIC KEY-----"
  awslocal kms get-public-key --key-id alias/signer \
    --query PublicKey --output text
  echo "-----END PUBLIC KEY-----"
} > pub.pem
```

> **Info.** Khóa công khai Ed25519 chỉ dài 32 byte, nên kết quả base64 đủ ngắn để nằm trên một dòng. Với các khóa dài hơn, bạn cần ngắt dòng ở 64 ký tự (`fold -w 64`) để tạo PEM hợp lệ, khóa Ed25519 không cần bước này.

Cách tương đương nhưng dài hơn (giải mã sang DER, rồi để `openssl` mã hóa lại thành PEM) cũng tạo ra tệp giống hệt:

```bash
awslocal kms get-public-key --key-id alias/signer \
  --query PublicKey --output text | base64 -d > pub.der
openssl pkey -pubin -inform DER -in pub.der -out pub.pem
```

Dù theo cách nào, bạn cũng sẽ có:

```text
-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEAKZ0GCR0MBIQGZowZI/1xmWjXlBy09I98JC6Tgn0l0L4=
-----END PUBLIC KEY-----
```

Dán nội dung đó vào dashboard làm khóa công khai của key. Khóa riêng tư vẫn nằm trong KMS, sử dụng `new AwsKmsSigner({ keyId: 'alias/signer' })` như trên để ký yêu cầu, KMS không bao giờ để lộ vật liệu khóa riêng tư.