# API oluştur

`POST /v1/apis` · izin `apis:write`

Ortamda yeni bir API oluşturur. `key`, `identifier` ve `name` zorunludur; verilmeyen isteğe bağlı alanlar varsayılanını alır. Tanımlayıcı ortamda tekildir (silinen API'nin tanımlayıcısı 90 gün ayrılı kalır). Yanıt, güncel sürümü gösteren `ETag` taşır. Yeniden denemeleri güvenli kılmak için `Idempotency-Key` başlığı gönderin.

## İstek

Gövde `application/json`. Bilinmeyen alanlar reddedilir.

| Alan | Tür | Zorunlu | Açıklama |
|---|---|---|---|
| `key` | string | evet | Kararlı yapılandırma anahtarı, `^[a-z0-9_-]{1,64}$`. Değişmez. |
| `identifier` | string | evet | Jeton kitlesi: https URL (sorgu ve parça yok) ya da `urn:<nid>:<nss>`; kanonik biçimde saklanır. Değişmez. `urn:idp:` ad alanı ayrılmıştır. |
| `name` | string | evet | 1-128 karakter. |
| `access_token_lifetime_s` | integer | hayır | 60-86400. Varsayılan 3600 (`mcp_profile` ile 600). |
| `token_format` | string | hayır | `jwt` (varsayılan) ya da `opaque`. |
| `rbac_mode` | string | hayır | Rol ve izinlerin jetona yansıması: `claims` (varsayılan) `permissions` ve `org_permissions` ekler; `off` ikisini de eklemez (`org_roles` yine eklenir); `enforce` ikisini ekler ve verilen scope'ları kullanıcının etkin izinleriyle sınırlar. |
| `allow_offline_access` | boolean | hayır | Varsayılan `true`. |
| `require_resource_indicator` | boolean | hayır | Varsayılan `false` (`mcp_profile` ile `true`). |
| `dpop_required` | boolean | hayır | Varsayılan `false`. |
| `mcp_profile` | boolean | hayır | https `identifier` ve `require_resource_indicator: true` ister. |
| `first_party_access` | string | hayır | `all` (varsayılan) ya da `granted_only`. |
| `introspection_applications` | dizi | hayır | Bu API'nin jetonlarını introspection ile sorgulayabilen uygulamalar (`app_…`), en çok 50, tekrarsız. Yalnız aynı ortamın `web` ve `m2m` uygulamaları. Varsayılan boş. |

### Introspection uygulamaları

Introspection ucu (`POST <issuer>/oauth2/introspect`, RFC 7662) bir erişim jetonu için `active: true` yanıtını yalnız iki çağırana verir: jetonun verildiği uygulamaya ya da jetonun `aud` değerindeki API'nin `introspection_applications` listesindeki uygulamaya. Diğer her çağıran `active: false` alır; böylece API'ler birbirinin jetonunu sorgulayamaz. Listeye yalnız aynı ortamın gizli uygulamaları (`web`, `m2m`) eklenebilir; liste küme olarak saklanır ve kimlik sırasıyla döner. Askıya alınmış uygulama listede kalır ama sorgulayamaz. Sistem API'sinin listesi yazılamaz.

## Yanıt

`201 Created`, `ETag` başlığı ve API:

```json
{
  "id": "api_01h455vb4pex5vsknk084sn02q",
  "key": "orders",
  "identifier": "https://api.example.com/orders",
  "name": "Orders API",
  "is_system": false,
  "access_token_lifetime_s": 3600,
  "token_format": "jwt",
  "rbac_mode": "claims",
  "allow_offline_access": true,
  "require_resource_indicator": false,
  "dpop_required": false,
  "mcp_profile": false,
  "first_party_access": "all",
  "introspection_applications": ["app_01h455vb4pex5vsknk084sn02r"],
  "created_at": "2026-10-05T12:00:00Z",
  "updated_at": "2026-10-05T12:00:00Z"
}
```

## Hatalar

| HTTP | code | Ne zaman |
|---|---|---|
| 400 | `unknown_field` | Gövdede yukarıda olmayan bir alan var (örneğin `id` ya da `is_system`). |
| 409 | `conflict` | Bu `key` ya da `identifier` ile bir API zaten var. |
| 415 | `unsupported_media_type` | İçerik türü `application/json` değil. |
| 422 | `validation_failed` | Bir alan eksik ya da geçersiz (`errors[].pointer`, örneğin `/identifier`). |
| 422 | `validation_failed` | `introspection_applications` öğesi bu ortamda yok (`unknown_application`), gizli değil (`not_confidential`), tekrarlı (`duplicate`) ya da `app_…` biçiminde değil (`invalid_value`); işaretçi istekteki indeksi gösterir. |
| 403 | `quota_exceeded` | Ortam API sayısı için teknik sınıra ulaştı. |
| 403 | `insufficient_permissions` | Kimlik bilgisinde `apis:write` yok. |

## Örnek

```bash
curl -X POST https://api.eu.keenauth.com/v1/apis \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"key":"orders","identifier":"https://api.example.com/orders","name":"Orders API"}'
```