Ejen AI · Pelajaran

Pengesahan: Kunci API dan OAuth

Token pembawa, pengepala kunci API dan aliran OAuth2 untuk akses API ejen.

Pelajaran 2 daripada 413 langkah

Pengesahan: Kunci API dan OAuth ialah pelajaran Ejen AI percuma di CoddyKit. Ini ialah pelajaran 2 daripada 4. Anda boleh membaca keseluruhan pelajaran di bawah secara percuma — kemudian berlatih secara praktikal dalam pelayar menggunakan penyunting kod terbina dalam dan tutor kecerdasan buatan 24/7. Pelajaran ini merupakan sebahagian daripada laluan pembelajaran Ejen AI, dan kemajuan anda disegerakkan merentas web serta aplikasi CoddyKit. Kursus Ejen AI merangkumi sejumlah 4 pelajaran.

Mengapa Pengesahan Penting untuk Ejen

Apabila ejen anda memanggil API luaran, pelayan perlu mengetahui siapa yang membuat permintaan itu. Pengesahan membuktikan identiti; keizinan menentukan perkara yang boleh anda lakukan. Tanpa pengesahan yang betul, setiap permintaan mengembalikan 401 Unauthorized dan ejen anda tidak dapat melakukan apa-apa.

Dua corak utama mendominasi pembangunan ejen: kunci API dan OAuth 2.0.

import requests

# Without auth — will get 401
response = requests.get('https://api.openai.com/v1/models')
print(response.status_code)  # 401 Unauthorized

# With API key in header — works
headers = {'Authorization': 'Bearer sk-proj-abc123'}
response = requests.get(
    'https://api.openai.com/v1/models',
    headers=headers
)
print(response.status_code)  # 200

Kunci API dalam Pengepala Authorization

Corak yang paling biasa ialah menghantar kunci API anda dalam pengepala Authorization sebagai token pembawa. Perkataan "Bearer" menandakan bahawa sesiapa yang memiliki token ini diberi keizinan — pelayan mempercayai pemegang kunci tersebut.

Corak ini digunakan oleh OpenAI, Anthropic, GitHub dan kebanyakan API moden.

import requests
import os

api_key = os.environ['OPENAI_API_KEY']

response = requests.post(
    'https://api.openai.com/v1/chat/completions',
    headers={
        'Authorization': f'Bearer {api_key}',
        'Content-Type': 'application/json'
    },
    json={
        'model': 'gpt-4o-mini',
        'messages': [{'role': 'user', 'content': 'Hello!'}]
    }
)
print(response.json()['choices'][0]['message']['content'])

Kunci API dalam Pengepala Tersuai (X-API-Key)

Sesetengah API — khususnya API yang lebih lama atau dalaman — menggunakan pengepala tersuai seperti X-API-Key dan bukannya Authorization: Bearer. Coraknya sama, cuma nama pengepalanya berbeza. Sentiasa semak dokumentasi API untuk mengetahui nama pengepala tepat yang dijangkakan.

import requests
import os

api_key = os.environ['SERVICE_API_KEY']

response = requests.get(
    'https://api.someservice.com/v1/data',
    headers={
        'X-API-Key': api_key,
        'Accept': 'application/json'
    }
)

if response.status_code == 200:
    data = response.json()
    print('Got data:', data)
elif response.status_code == 401:
    print('Invalid API key — check X-API-Key header')

Menyimpan Kredensial dalam Pemboleh Ubah Persekitaran

Jangan sekali-kali menulis terus kunci API dalam kod sumber anda. Jika anda menghantar kunci ke repositori awam, bot akan menemuinya dan menyalahgunakannya dalam masa beberapa saat. Corak yang betul ialah menyimpan kredensial dalam pemboleh ubah persekitaran dan membacanya semasa masa jalan menggunakan os.environ.

Gunakan os.environ.get() bersama mesej ralat yang jelas jika kunci itu tiada.

import os

os.environ['OPENAI_API_KEY'] = 'sk-proj-abc123xyz789'  # simulate a set env var

api_key = os.environ.get('OPENAI_API_KEY')
if not api_key:
    raise EnvironmentError(
        'OPENAI_API_KEY environment variable not set. '
        'Run: export OPENAI_API_KEY=your-key-here'
    )

print('API key loaded from environment (never hard-code it in source)')

Menggunakan python-dotenv untuk Pembangunan Setempat

Semasa pembangunan, simpan kunci anda dalam fail .env di akar projek. Gunakan pustaka python-dotenv untuk memuatkannya secara automatik. Tambahkan .env kepada .gitignore supaya fail itu tidak pernah dihantar ke repositori.

# .env file (never commit this!)
# OPENAI_API_KEY=sk-proj-abc123
# ANTHROPIC_API_KEY=sk-ant-xyz456
# GITHUB_TOKEN=ghp_abc789

# In your Python code:
from dotenv import load_dotenv
import os

load_dotenv()  # loads .env into os.environ

openai_key = os.environ['OPENAI_API_KEY']
anthropic_key = os.environ['ANTHROPIC_API_KEY']
github_token = os.environ['GITHUB_TOKEN']

print('Keys loaded successfully')

Apakah OAuth 2.0?

OAuth 2.0 ialah piawaian untuk keizinan yang diwakilkan. Daripada memberikan kata laluan pengguna kepada ejen anda, OAuth membolehkan pengguna memberi keizinan kepada ejen anda untuk bertindak bagi pihak mereka, dengan skop dan tempoh masa yang terhad. Ia digunakan oleh Google, GitHub, Slack dan Salesforce.

Konsep utamanya ialah ejen anda mendapat token akses selepas aliran keizinan, kemudian menggunakan token itu untuk panggilan API.

# OAuth flow overview:
#
# 1. Agent redirects user to:
#    https://auth.provider.com/oauth/authorize
#      ?client_id=YOUR_CLIENT_ID
#      &redirect_uri=http://localhost:8080/callback
#      &scope=read:repo%20write:issues
#      &response_type=code
#
# 2. User logs in and grants permission
# 3. Provider redirects to your callback with ?code=AUTH_CODE
# 4. Agent exchanges code for access_token
# 5. Agent uses access_token for API calls

print('OAuth flow: authorize -> code -> token -> API calls')

Aliran Kelayakan Klien OAuth2

Aliran kelayakan klien ialah aliran OAuth paling ringkas untuk agen — tiada interaksi pengguna diperlukan. Agen anda mengesahkan identitinya menggunakan ID klien dan rahsianya sendiri untuk mendapatkan token. Aliran ini digunakan untuk komunikasi mesin-ke-mesin (M2M).

Anda POST kelayakan anda ke titik akhir token dan menerima token akses yang sah untuk tempoh singkat.

import requests
import os

client_id = os.environ['OAUTH_CLIENT_ID']
client_secret = os.environ['OAUTH_CLIENT_SECRET']
token_url = 'https://auth.example.com/oauth/token'

# Request an access token
response = requests.post(token_url, data={
    'grant_type': 'client_credentials',
    'client_id': client_id,
    'client_secret': client_secret,
    'scope': 'read:data write:tasks'
})

token_data = response.json()
access_token = token_data['access_token']
expires_in = token_data['expires_in']  # seconds
print(f'Token valid for {expires_in}s')

Menggunakan Token OAuth dalam Panggilan API

Setelah anda mempunyai token akses OAuth, gunakannya sama seperti kunci API — dalam pengepala Authorization: Bearer. Perbezaannya ialah token OAuth akan luput, jadi agen anda mesti mengendalikan penyegaran token sebelum membuat panggilan.

import requests
import os
import time

class OAuthClient:
    def __init__(self, client_id, client_secret, token_url):
        self.client_id = client_id
        self.client_secret = client_secret
        self.token_url = token_url
        self.access_token = None
        self.token_expiry = 0

    def get_token(self):
        if time.time() < self.token_expiry - 60:  # 60s buffer
            return self.access_token
        r = requests.post(self.token_url, data={
            'grant_type': 'client_credentials',
            'client_id': self.client_id,
            'client_secret': self.client_secret
        })
        data = r.json()
        self.access_token = data['access_token']
        self.token_expiry = time.time() + data['expires_in']
        return self.access_token

    def get(self, url):
        token = self.get_token()
        return requests.get(url, headers={'Authorization': f'Bearer {token}'})

OAuth 2.0 dengan Pustaka google-auth

Untuk API Google, pustaka google-auth mengendalikan semua kerumitan OAuth untuk anda. Pustaka ini mengurus penyegaran token secara automatik, membaca kelayakan daripada fail JSON dan melampirkan token pada permintaan melalui AuthorizedSession.

from google.oauth2 import service_account
from google.auth.transport.requests import AuthorizedSession

# Load service account credentials from JSON file
credentials = service_account.Credentials.from_service_account_file(
    'service-account.json',
    scopes=[
        'https://www.googleapis.com/auth/gmail.readonly',
        'https://www.googleapis.com/auth/calendar.events'
    ]
)

# AuthorizedSession auto-refreshes tokens
session = AuthorizedSession(credentials)

response = session.get(
    'https://www.googleapis.com/gmail/v1/users/me/messages'
)
print(response.json())

Amalan Terbaik Keselamatan Kunci API

Melindungi kunci API amat penting untuk keselamatan agen. Ikuti peraturan berikut:

  • Simpan kunci dalam pemboleh ubah persekitaran atau pengurus rahsia (AWS Secrets Manager, HashiCorp Vault)
  • Jangan sekali-kali merekodkan kunci — samarkannya dalam keluaran
  • Tukar kunci secara berkala dan batalkan kunci yang terjejas dengan segera
  • Gunakan prinsip keistimewaan minimum — minta hanya skop yang diperlukan oleh agen anda
  • Tetapkan senarai benarkan IP pada kunci API jika pembekal menyokongnya
import os

os.environ['OPENAI_API_KEY'] = 'sk-proj-abc123xyz789'

def get_key(env_var):
    key = os.environ.get(env_var)
    if not key:
        raise EnvironmentError(f'Missing required env var: {env_var}')
    return key

def mask_key(key):
    if len(key) < 8:
        return '***'
    return key[:4] + '...' + key[-4:]

api_key = get_key('OPENAI_API_KEY')
print(f'Using key: {mask_key(api_key)}')

Mengendalikan 401 Tidak Dibenarkan dalam Agen Anda

Apabila agen menerima respons 401 Unauthorized, agen tidak boleh mencuba semula secara membuta tuli — tindakan itu membazirkan kuota had kadar. Sebaliknya, semak sama ada token telah luput (cuba menyegarkannya) atau sama ada kunci itu sendiri tidak sah (beri amaran serta-merta supaya manusia boleh membetulkannya).

import requests
import os

def call_api_with_auth_check(url, api_key):
    response = requests.get(
        url,
        headers={'Authorization': f'Bearer {api_key}'}
    )
    if response.status_code == 401:
        error = response.json().get('error', {})
        code = error.get('code', 'unknown')
        if code == 'token_expired':
            print('Token expired — refresh needed')
            # trigger token refresh flow
        else:
            raise PermissionError(
                f'API key rejected: {error.get("message", "401 Unauthorized")}'
            )
    response.raise_for_status()
    return response.json()

Semakan Pantas: Penyimpanan Kunci API

Uji pemahaman anda tentang pengurusan kelayakan.

Ulang Kaji Pengesahan

Anda telah mempelajari dua corak pengesahan utama untuk agen:

  • Kunci API — dihantar dalam pengepala Authorization: Bearer TOKEN atau X-API-Key; ringkas dan tanpa keadaan
  • OAuth 2.0 — aliran kelayakan klien untuk M2M; token akan luput dan mesti disegarkan
  • Sentiasa simpan kunci dalam pemboleh ubah persekitaran, bukan dalam kod sumber
  • Gunakan python-dotenv secara setempat; gunakan pemboleh ubah persekitaran atau pengurus rahsia dalam persekitaran pengeluaran
  • Kendalikan respons 401 dengan menyemak sama ada token telah luput atau kunci tidak sah

Pengendalian pengesahan yang kukuh ialah asas bagi setiap agen yang boleh dipercayai.

Percuma untuk bermula

Pelajari Ejen AI dengan tutor kecerdasan buatan — percuma

Tulis dan jalankan kod sebenar dalam pelayar anda, dapatkan bantuan segera daripada tutor kecerdasan buatan yang tersedia 24/7, dan sambung semula dari tempat anda berhenti di web atau dalam aplikasi.

Kursus
60
Pelajaran
239

Soalan Lazim

Adakah pelajaran “Pengesahan: Kunci API dan OAuth” percuma?

Ya — teks penuh “Pengesahan: Kunci API dan OAuth” boleh dibaca secara percuma di web ini. Untuk berlatih secara interaktif menggunakan penyunting kod terbina dalam dan tutor kecerdasan buatan 24/7, serta membuka kunci baki kursus Ejen AI, tingkat taraf kepada CoddyKit PRO. Kursus Ejen AI merangkumi sejumlah 4 pelajaran.

Apakah yang akan saya pelajari dalam “Pengesahan: Kunci API dan OAuth”?

Token pembawa, pengepala kunci API dan aliran OAuth2 untuk akses API ejen. Anda berlatih Ejen AI menggunakan kod praktikal yang dijalankan terus dalam pelayar, manakala tutor kecerdasan buatan 24/7 menjawab soalan anda semasa anda mengikuti pelajaran.

Adakah saya memerlukan pengalaman untuk memulakan Ejen AI?

Tiada pengalaman terdahulu diperlukan. Pembelajaran Ejen AI di CoddyKit disusun untuk pelajar daripada peringkat pemula hingga lanjutan, jadi anda boleh bermula di sini atau dari awal dan belajar mengikut kadar anda sendiri. Ini ialah pelajaran 2 daripada 4.

Berapa lamakah pelajaran “Pengesahan: Kunci API dan OAuth” diambil?

Kebanyakan pelajaran CoddyKit mengambil masa kira-kira 5–10 minit. Setiap pelajaran ringkas dan interaktif, jadi anda boleh membuat kemajuan secara berterusan dan menyambung tepat dari tempat anda berhenti di web atau aplikasi.

Bolehkah saya menulis dan menjalankan kod dalam pelajaran Ejen AI ini?

Ya. Setiap pelajaran Ejen AI menyertakan penyunting kod terbina dalam, jadi anda boleh menulis dan menjalankan kod sebenar terus dalam pelayar serta menerima maklum balas kecerdasan buatan serta-merta — tanpa memerlukan persediaan setempat.

Semua pelajaran dalam kursus ini

  1. Asas REST API untuk Pembangun Ejen
  2. Pengesahan: Kunci API dan OAuth
  3. Mengendalikan Respons dan Ralat API
  4. Pengehadan Kadar dan Logik Percubaan Semula
← Kembali ke Ejen AI