How to restrict API access with Static Access Token

Kuroco's API security

You have following 4 options for Kuroco's API security:

• None
• Static Access Token
• Dynamic Access Token
• Cookie

You can set "None" if you want to create and test a temporary development API, or if you want to use completely open data.

However, if you set the API security setting to "None", anyone can use the API, and it will be possible to accept API requests indiscriminately from the outside.

If this situation is not as expected, you can use the Static Access Token function to impose some restrictions. This tutorial explains how to apply access restrictions using Static Access Token.

Note:
The character string of StaticToken becomes information that can be viewed from the outside by referring to the network communication of the public site and the description in the JS file. Therefore, if you want to restrict secure information, please do so by restricting login authentication by Dynamic Token / Cookie restriction instead of Static Access Token or by restricting API by browsing group.

How to restrict API access by Static Access Token

This section explains how to restrict API access by Static Access Token.

1. Configure the security of Kuroco API

On any API list page, click [Security].

Change the "Security" to Static Access Token and click [Save]

2. Issue Static Access Token

Click [Swagger UI] on the API list page.

Enter "Valid Until" of "Generate Static Access Token" at the top of Swagger UI page and click [Generate].

Token will be issued. You will need it later so save it.

The configuration on the Kuroco management page is now complete.

3. API Access Configuration

As an example, here are code snippets for Nuxt 3 and Next.js.

info

In this tutorial, the following versions are used:

• Nuxt3: v3.14.0
• Next.js: v15.0.3 (Using App Router)

First, install the necessary packages for the tutorial:

Nuxt3

No additional packages are required for Nuxt 3.

Next.js

terminal

npm install axios

4. Setting Environment Variables

Nuxt3

.env

NUXT_STATIC_TOKEN=YOUR_STATIC_TOKEN_HERE
NUXT_PUBLIC_API_BASE_URL=https://your-api-endpoint.com

Next.js

.env

STATIC_TOKEN=YOUR_STATIC_TOKEN_HERE
NEXT_PUBLIC_API_URL=https://your-api-endpoint.com

Note

Environment variables prefixed with NUXT_PUBLIC_/NEXT_PUBLIC_ are accessible on the client side. For more details, refer to the following links:

• Nuxt 3 Documents - runtime-config
• Next.js Documents - environment-variables

5. Updating Configuration Files

Nuxt3

nuxt.config.ts

export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      staticToken: process.env.NUXT_STATIC_TOKEN,
      publicApiBaseUrl: process.env.NUXT_PUBLIC_API_BASE_URL
    }
  }
})

Next.js

next.config.js

/** @type {import('next').NextConfig} */
const nextConfig = {
  env: {
    STATIC_TOKEN: process.env.STATIC_TOKEN
  }
}

module.exports = nextConfig

6. Setting Static Access Token in API Request Headers

Nuxt3

/plugins/fetch.ts

export default defineNuxtPlugin(() => {
  const config = useRuntimeConfig()

  return {
    provide: {
      customFetch: (url: string, options = {}) => {
        return useFetch(url, {
          baseURL: config.public.apiBase as string,
          headers: {
            'x-rcms-api-access-token': config.public.staticToken as string
          },
          ...options
        })
      }
    }
  }
})

info

The Kuroco Beginner's Guide does not cover the use of plugins, but this is a good opportunity to explore it in the official documentation:

• Nuxt 3 Documents - plugins

Next.js

/lib/axios.ts

import axios from 'axios'

export const api = axios.create({
  baseURL: process.env.NEXT_PUBLIC_API_URL,
  headers: {
    'x-rcms-api-access-token': process.env.STATIC_TOKEN
  }
})

7. API Usage Examples

Nuxt3

/pages/example.vue

<script setup>
// Basic usage
const { $customFetch } = useNuxtApp()
const { data: response } = await $customFetch('/api/endpoint');

// Example of overriding headers
const { $customFetch } = useNuxtApp()
const { data: customData } = await $customFetch('/api/endpoint', {
  headers: {
    'x-rcms-api-access-token': 'different-token'
  }
}
</script>
<template>
  <div>
    <div v-if="pending">Loading...</div>
    <div v-else>
      <pre>{{ data }}</pre>
    </div>
  </div>
</template>

Next.js

/app/example.tsx

// Using API client
import { api } from '@/lib/axios'

export default function Page() {
  const [data, setData] = useState(null)

  useEffect(() => {
    const fetchData = async () => {
      const response = await api.get('/api/endpoint')
      setData(response.data)
    }
    fetchData()
  }, [])

  return <div>{/* Display data */}</div>
}

// Using built-in fetch
async function getData() {
  const res = await fetch('https://api-endpoint.com/api/endpoint', {
    headers: {
      'x-rcms-api-access-token': process.env.STATIC_TOKEN
    }
  })
  return res.json()
}

// Using in App Router Server Component
export default async function Page() {
  const data = await getData()
  return <div>{/* Display data */}</div>
}

info

• Nuxt 3: Examples of using useFetch / $fetch to automatically include the static token in headers.
• Next.js: Examples of using fetch or axios to set static tokens in request headers.

tip

• Set the static access token as a key in the request header X-RCMS-API-ACCESS-TOKEN to send requests and retrieve data.

caution

• Depending on your project, it is recommended to write environment variables in separate files such as .env or .env.local etc... Make sure to add environment variable files to .gitignore to prevent committing sensitive information to the repository.

The configuration of API access restriction by Static Access Token is now complete.

Reference

• API Security
• How to check the API security using Swagger UI