SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillskuroco-api-integration

kuroco-api-integration

Coding & development

View repository

Updated 10-15 21:10

About this skill

Kuroco API integration patterns

We provide best practices for API design and implementation of Kuroco HeadlessCMS.

Documentation reference: /kuroco-docs You can search and reference the official Kuroco documentation using the skill.

Endpoint design

Basic structure

Kuroco API paths use the following format:

https://{サイトキー}.g.kuroco.app/rcms-api/{api_id}/{endpoint_path}

Example:

https://example.g.kuroco.app/rcms-api/1/news
https://example.g.kuroco.app/rcms-api/1/member/login

Main items in endpoint settings

Item Description Example
Path Endpoint URL news, member/list
Model Operation target Topics, Member, InquiryForm
Operation Operation type list, details, insert, update, delete
Cache Response cache period 86400 (1 day)
Rate limit Request count limit 100 times/minute
Authentication required Whether login is required true/false

Main categories and models

Authentication

Operation Description Method
login_challenge Login POST
token Obtain access token POST
logout Logout POST
profile Obtain logged-in user information GET
reminder Password Reminder POST

Content (Topics)

Operation Description Method
list Obtain list GET
details Obtain details GET
insert Add new POST
update Update POST
delete Delete POST
bulk_upsert Bulk update POST

Member (Member)

Operation Description Method
list Member list GET
details Member details GET
insert Member registration POST
update Member update POST

Form (InquiryMessage/InquiryForm)

Operation Description Method
send Form submission POST
list Response list GET
details Response details GET

Security settings

Detailed reference: For details on security settings, refer to references/security-settings.md .

Documentation sync: docs/ If the directory is not synced, ask the user, "The Kuroco documentation is not synced./kuroco-docs May I sync it with the skill?", and after syncing, refer to docs/management/api-security.md , etc.

Authentication methods

In the admin panel: [API] → [Security], select from 4 types.

Authentication method Use case Header
None For development/testing (not recommended for production) Not required
Static access token Server-to-server communication, public API X-RCMS-API-ACCESS-TOKEN: {固定トークン}
Dynamic access token Sites requiring login (JWT) X-RCMS-API-ACCESS-TOKEN: {動的トークン}
Cookie Websites requiring login credentials: 'include'(frontend side)

1. Cookie authentication (recommended for web apps)

Session-based authentication.credentials: 'include' is required.

// ログイン
const response = await fetch('https://example.g.kuroco.app/rcms-api/1/login', {
  method: 'POST',
  credentials: 'include',  // 必須
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'password123'
  })
})

// レスポンス例
// {
//   "grant_token": "xxxxx",
//   "status": 0,
//   "member_id": 123
// }

Notes:

  • Third-party cookie issue (blocked by Safari, etc.)
  • The API domain and frontend must be set to **the same domain (different subdomain)** (first-party cookie conversion)
    • Example: api.example.com と www.example.com
  • When there are multiple cookie-authenticated APIs, the authentication state isshared

2. Token authentication (recommended for mobile apps)

JWT-based authentication. Attach the token to the header.

// トークン取得
const tokenResponse = await fetch('https://example.g.kuroco.app/rcms-api/1/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'password123'
  })
})

const { access_token, refresh_token } = await tokenResponse.json()

// レスポンス例
// {
//   "access_token": {
//     "value": "eyJhbGciOiJS...",
//     "expiresAt": "2024-01-01T12:00:00+09:00"
//   },
//   "refresh_token": {
//     "value": "xxxxxx",
//     "expiresAt": "2024-01-08T12:00:00+09:00"
//   }
// }

// API呼び出し時
const response = await fetch('https://example.g.kuroco.app/rcms-api/1/news', {
  headers: {
    'X-RCMS-API-ACCESS-TOKEN': access_token.value
  }
})

Prerequisites: At least one user,login_challenge + token endpoint is required. When there are multiple token-authenticated APIs, the authentication state isnot shared。

3. StaticToken authentication (server-to-server communication)

API access restriction using a fixed token.

const response = await fetch('https://example.g.kuroco.app/rcms-api/1/internal-api', {
  headers: {
    'X-RCMS-API-ACCESS-TOKEN': 'your-static-token-here'
  }
})

Configuration location: Admin panel → API → Security → StaticToken

Note: If a static token is embedded in the frontend, it becomes visible to users. Operation must assume token rotation in case of leakage.

IP address restriction

Admin panel: [API] → [Security] → [IP address restriction]

Only access from specified IP addresses is allowed.

Specified format Example Description
Individual IP 192.0.2.1 Single IP address
CIDR 192.0.2.0/24 Subnet unit
Range specification 192.0.2.1-192.0.2.2 IP range using a hyphen

IP Address Group: Define IPSETS_* with the constant feature, and it can be referenced with[[IPSETS_*]] (docs/faq/is-it-possible-to-set-multiple-ip-addresses-at-once.mdx reference).

CORS settings

Admin panel: [API] → [Security] → [CORS]

Item Corresponding header Description
CORS_ALLOW_ORIGINS Access-Control-Allow-Origin Allowed origins (Wildcard*is deprecated）
CORS_ALLOW_METHODS Access-Control-Allow-Methods Allowed HTTP methods
CORS_ALLOW_HEADERS Access-Control-Allow-Headers Allowed request headers
CORS_MAX_AGE Access-Control-Max-Age Preflight cache seconds
CORS_ALLOW_CREDENTIALS Access-Control-Allow-Credentials Allow cookie sending

CSRF protection: CORS + Content-Type: application/json protects against CSRF attacks in modern browsers. Using a wildcard eliminates the protective effect, so always specify a specific domain.

Delay in reflecting changes: After changing CORS settings, it is cached in the browser for CORS_MAX_AGE minutes. For immediate reflection, clear the browser cache or set to CORS_MAX_AGE を 0 .

API request restrictions

Restriction type Description
None No restriction
GroupAuth Logged-in user'sGroup permissionis checked, and allowed only if it matches
MemberCustomSearchAuth Logged-in userCustom Member Filteris allowed only if it matches the conditions of

Priority order of viewing restrictions

Restrictions when returning content are evaluated in the following order (higher priority first):

  1. API → IP address restriction(entire API)
  2. Endpoint → API request restriction(Per endpoint)
  3. Content definition → API request limit
  4. Content category → API request limit
  5. Individual content → API request limit

Response restriction via post-processing

Admin panel: [API] → Endpoint → [Post-processing]

Exclude unnecessary fields from API responses and control published information:

Processing type Description
Output allowlist Return only specified fields (whitelist). Example: list.subject, pageInfo
Output conversion list Delete fields, rename fields, apply conversion functions
Custom processing Custom logic using Smarty templates

Performance Tip: Placing the output allowlist before other processes makes it effective at the SQL level.

Platform Security

Infrastructure-level security provided by the Kuroco platform:

  • Communication: Full HTTPS encryption, automatic TLS certificate management
  • Defense: WAF, CDN, DDoS protection (Fastly DDoS Protection as an option)
  • Authentication integration: SAML/OAuth external login, client certificate (optional)
  • Audit: Access Log, Application Log
  • Certification: ISMS (ISO 27001), ISMS Cloud (ISO 27017), Privacy Mark
  • Diagnosis: Daily container vulnerability scans, automated diagnosis via VADDY integration

Configuration changes via the management API (mng_api)

API security settings can be configured not only from the admin panel but also via themanagement API./kuroco-mng-api-browser You can execute the management API via a browser using the skill.

Cache strategy

Recommended settings

Use Case Cache duration Setting value
Static content (news, etc.) 1 day 86400
Content with low update frequency 1 week 604800
Requires real-time updates No Cache 0
APIs requiring authentication No Cache 0

Important: When data such as content or members is updated, the cache is automatically cleared.

Cache Header

Can be checked in the response header:

Cache-Control: max-age=86400

Rate limiting

Response Header

x-rcms-ratelimit-limit: 100      # 制限数
x-rcms-ratelimit-remaining: 95   # 残りリクエスト数
x-rcms-ratelimit-reset: 60       # リセットまでの秒数

Handling 429 errors

const response = await fetch(url)

if (response.status === 429) {
  const resetTime = response.headers.get('x-rcms-ratelimit-reset')
  console.log(`流量制限超過。${resetTime}秒後に再試行してください`)
}

API call patterns

List retrieval (with pagination)

async function fetchNewsList(page = 1, perPage = 10) {
  const params = new URLSearchParams({
    pageID: page,
    cnt: perPage
  })

  const response = await fetch(
    `https://example.g.kuroco.app/rcms-api/1/news?${params}`,
    { credentials: 'include' }
  )

  const data = await response.json()

  // レスポンス構造
  // {
  //   "list": [...],
  //   "pageInfo": {
  //     "totalCnt": 100,
  //     "perPage": 10,
  //     "totalPageCnt": 10,
  //     "pageNo": 1
  //   }
  // }

  return data
}

Filter search

// filter パラメータで検索
const params = new URLSearchParams({
  filter: 'subject contains "重要"',
  order_by: 'ymd desc'
})

const response = await fetch(
  `https://example.g.kuroco.app/rcms-api/1/news?${params}`,
  { credentials: 'include' }
)

Detail retrieval

async function fetchNewsDetail(topicsId) {
  const response = await fetch(
    `https://example.g.kuroco.app/rcms-api/1/newsdetail/${topicsId}`,
    { credentials: 'include' }
  )

  const data = await response.json()

  // レスポンス構造
  // {
  //   "details": {
  //     "topics_id": 1,
  //     "subject": "タイトル",
  //     "contents": "<p>本文</p>",
  //     ...
  //   }
  // }

  return data.details
}

Content creation

async function createNews(newsData) {
  const response = await fetch(
    'https://example.g.kuroco.app/rcms-api/1/news/insert',
    {
      method: 'POST',
      credentials: 'include',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        subject: newsData.title,
        contents: newsData.body,
        ymd: newsData.date,
        topics_flg: 1  // 1: 公開, 0: 非公開
      })
    }
  )

  return response.json()
}

Error Handling

Main error codes

Code Description Action
400 Request Error Check the request parameters
401 Authentication error Check login status and token
403 Permission error Check the API permission settings
404 Resource does not exist Check the path and ID
429 Rate limit exceeded Wait until retry
500 Server Error Contact Kuroco Support

Error response example

{
  "errors": [
    {
      "code": "authentication_error",
      "message": "ログインが必要です"
    }
  ]
}

Error handling implementation

async function apiRequest(url, options = {}) {
  try {
    const response = await fetch(url, {
      credentials: 'include',
      ...options
    })

    if (!response.ok) {
      const errorData = await response.json()

      switch (response.status) {
        case 401:
          // ログイン画面へリダイレクト
          throw new Error('認証が必要です')
        case 403:
          throw new Error('アクセス権限がありません')
        case 429:
          throw new Error('リクエスト制限を超えました')
        default:
          throw new Error(errorData.errors?.[0]?.message || 'APIエラー')
      }
    }

    return response.json()
  } catch (error) {
    console.error('API Error:', error)
    throw error
  }
}

Related skills

  • /kuroco-content-management - Content CRUD operations
  • /kuroco-frontend-integration - API call patterns in Nuxt.js/Next.js
  • /kuroco-ai-deployment - AI automatic deployment (via mng_api, browser authentication)
  • /kuroco-mng-api-browser - Management API (mng_api) operations

Related documents

In-skill reference

  • references/security-settings.md - Detailed reference for security settings

Kuroco official documentation (docs/)

  • docs/management/api-security.md - API security settings (authentication methods, IP restrictions)
  • docs/management/api-list.md - API list/CORS settings
  • docs/management/api-postprocessing.md - API post-processing settings
  • docs/reference/endpoint-settings.md - List of endpoint setting items
  • docs/reference/post-processing.md - Detailed reference for post-processing
  • docs/tutorials/configure-endpoint.md - How to configure endpoints
  • docs/tutorials/login.md - Login implementation
  • docs/tutorials/restricting-api-access-with-statictoken.md - StaticToken authentication
  • docs/reference/api-cache.md - API Cache
  • docs/reference/filter-query.md - Filter Query
  • docs/about/security.md - Platform security overview
  • docs/faq/in-what-order-are-viewing-restrictions-applied.mdx - Priority order of access restrictions
  • docs/faq/cors-and-content-type-prevent-csrf-attacks.mdx - CSRF countermeasures
  • docs/faq/the-api-returns-403-forbidden-even-though-no-restrictions-are-applied.mdx - Resolving 403 errors