Thu hồi API KEY

Khi API Key không còn cần thiết, bị lộ ra bên ngoài, hoặc cần vô hiệu hóa vì lý do bảo mật, bạn có thể thu hồi (revoke) key đó. Key bị thu hồi sẽ ngừng hoạt động ngay lập tức và không thể khôi phục lại.

Cảnh báo: Thao tác thu hồi là không thể hoàn tác. Sau khi revoke, mọi request sử dụng key này sẽ bị từ chối. Nếu bạn cần key mới cho cùng mục đích, hãy tạo một API Key mới hoặc sử dụng chức năng Regenerate thay vì Revoke.

Endpoint

POST `/api/v1.0/integration/api-keys/{id}/revoke`

Thu hồi vĩnh viễn một API Key. Key sẽ chuyển sang trạng thái inactive và không thể sử dụng được nữa.

Headers

Header	Kiểu	Bắt buộc	Mô tả
`Authorization`	string	Có	Token xác thực. Định dạng: `Bearer {{token}}`

Path Parameters

Tham số	Kiểu	Bắt buộc	Mô tả
`id`	string	Có	ID của API Key cần thu hồi. Lấy từ danh sách API Keys

Code mẫu

curl -X POST "{{protocol}}://{{host}}:{{port}}/api/v1.0/integration/api-keys/key_abc123def456/revoke" \
  -H "Authorization: Bearer {{token}}"

const axios = require('axios')

const keyId = 'key_abc123def456'

const response = await axios.post(
  `{{protocol}}://{{host}}:{{port}}/api/v1.0/integration/api-keys/${keyId}/revoke`,
  {},
  {
    headers: {
      'Authorization': 'Bearer {{token}}'
    }
  }
)

console.log('Kết quả:', response.data.message)

import requests

key_id = 'key_abc123def456'
url = f'{{protocol}}://{{host}}:{{port}}/api/v1.0/integration/api-keys/{key_id}/revoke'
headers = {
    'Authorization': 'Bearer {{token}}'
}

response = requests.post(url, headers=headers)

data = response.json()
print('Kết quả:', data['message'])

Response thành công

HTTP 200 OK

{
  "success": true,
  "message": "API Key đã được thu hồi thành công",
  "id": "key_abc123def456",
  "status": "inactive",
  "revokedAt": "2026-04-07T15:30:00.000Z"
}

Mô tả Response

Trường	Kiểu	Mô tả
`success`	boolean	`true` nếu thu hồi thành công
`message`	string	Thông báo kết quả
`id`	string	ID của API Key đã thu hồi
`status`	string	Trạng thái mới: `inactive`
`revokedAt`	string	Thời gian thu hồi (ISO 8601)

Lỗi thường gặp

HTTP Code	Nguyên nhân	Cách xử lý
`401`	Token không hợp lệ hoặc hết hạn	Lấy lại token xác thực mới
`403`	Không có quyền thu hồi API Key	Liên hệ Alohub để được cấp quyền
`404`	Không tìm thấy API Key với ID đã cung cấp	Kiểm tra lại ID key từ danh sách API Keys
`410`	API Key đã bị thu hồi trước đó	Key này đã inactive, không cần thao tác thêm

Khi nào nên Revoke vs Regenerate?

Tình huống	Hành động	Lý do
Key bị lộ, vẫn cần kết nối API	Regenerate	Vô hiệu key cũ, tạo key mới cùng cấu hình — giảm thời gian gián đoạn
Key hết hạn, vẫn cần kết nối API	Regenerate	Gia hạn nhanh mà không cần cấu hình lại scopes
Ngừng tích hợp với ứng dụng bên thứ ba	Revoke	Cắt quyền truy cập vĩnh viễn, không cần key thay thế
Phát hiện truy cập bất thường từ key	Revoke ngay	Chặn truy cập trái phép càng nhanh càng tốt
Nhân viên quản lý key rời công ty	Regenerate hoặc Revoke	Tùy theo còn cần kết nối hay không

Bảo mật: Khi phát hiện API Key bị lộ hoặc có dấu hiệu truy cập trái phép, hãy thu hồi key ngay lập tức. Liên hệ Alohub nếu cần hỗ trợ kiểm tra nhật ký truy cập.