Can I call an external API with OAuth from custom functions?

Yes. When the name of an OAuth connection is specified in oauth_connection of the api plugin, the request is sent with the access token obtained by that connection in the Authorization header. Create the OAuth connection in advance and make its status Active with [Connect / reauthorize].

{assign_array var=queries values=""}
{append var=queries index="limit" value=10}
{api oauth_connection="example_api"
     endpoint="https://api.example.com/v1/items"
     queries=$queries
     json_var="result" status_var="ok" http_code_var="http_code" error_var="oauth_error"}

{if $ok}
    {* $result contains the decoded JSON *}
{elseif $oauth_error}
    {* OAuth connection error. $oauth_error contains the reason *}
{else}
    {* The destination returned a non-2xx response. Check $http_code *}
{/if}

Build the query parameter array with assign_array and append, then pass it to queries. Array literals such as ['limit' => 10] cannot be used in Kuroco templates. See Building arrays in templates — best practices.

note

Even when the destination is an external MCP server, the api plugin only sends an HTTP request with the OAuth access token. Calling MCP tools is not supported.

Creating an OAuth connection

The following steps connect to an external API. See OAuth connections for details of each field. Creating an OAuth connection requires a superuser.

1. Click [External system integration] -> [OAuth connections], then click [Add].
2. Enter [Name] and select External API (manual setup) in [Connection type]. [Name] is the value specified in oauth_connection of the api plugin.
3. Select [Grant type].
4. Enter [Resource URL], [Scope], and the fields in [Client] and [Authorization server] according to the values issued or published by the destination service. For JWT Bearer, also enter [JWT subject], [JWT audience], and [Private key (PEM)].
5. For Authorization Code + PKCE, register the URI shown in [Redirect URI to register] in the client settings of the destination service.
6. Click [Save].
7. Click [Connect / reauthorize] and obtain a token by following Authorization steps.
8. Confirm that [Status] is Active.

tip

To connect to an external MCP server, select External MCP server (auto-discovery) in [Connection type], click [Save], run [Discover metadata], and then run [Connect / reauthorize]. See OAuth connections for details.

Where it can be used and who can save it

• api with oauth_connection can be used only in custom functions and batch processes. It cannot be saved anywhere else, and it also raises an error at runtime.
• Processing that contains api with oauth_connection can be saved only by a superuser.

Token refresh and retry

• If the access token has expired, the token is refreshed or obtained again before the request.
• If the destination returns 401, the token is refreshed or obtained again once and the same request is resent. If the retry also returns 401, the status of the OAuth connection becomes Reauthorization required and reauthorization_required is stored in error_var.
• If the authorization server returns 5xx or 429, or a network failure occurs while refreshing the token, the stored refresh token is retained.

caution

The retry after 401 is also performed for methods such as POST. If the destination supports an idempotency key (such as the Idempotency-Key header), specify it in headers as needed.

Limitations

The following limitations apply when oauth_connection is specified.

• endpoint is required. Only URLs with the same origin as the [Resource URL] of the OAuth connection and the path of the resource URL or paths below it can be specified. The token is never sent to other URLs.
• Only public HTTPS URLs on port 443 can be used. URLs with an IP address as the host and private IP addresses cannot be accessed.
• Redirects are not followed. If the destination returns 3xx, an error occurs.
• Responses are limited to 16 MiB. Authorization server metadata and token responses are limited to 64 KiB.
• cache_time, files, dl_flg, tmp_dl_flg, sslcert, sslkey, and cainfo cannot be used.
• Authorization, Host, and Proxy-Authorization cannot be specified in headers.

If these attributes are specified incorrectly, a template error occurs.

The behavior of api without oauth_connection is unchanged.

Results

Result	status_var	http_code_var	error_var
The destination returned 2xx	1	HTTP status code	Empty
The destination returned a non-2xx response	0	HTTP status code	Empty
The request was not sent because of an OAuth connection error	0	0	Error reason

The main values stored in error_var are as follows.

Value	Description
reauthorization_required	The OAuth connection needs authorization. Stored when the status is Reauthorization required or Revoked, or when a token cannot be obtained or refreshed for Authorization Code + PKCE. Run [Connect / reauthorize] in [OAuth connections] of the management screen.
not_found	No OAuth connection with the specified name exists.
invalid_resource	endpoint is outside the resource URL of the OAuth connection.
unsafe_endpoint	The destination is not a public HTTPS URL.
redirect_not_allowed	The destination returned a redirect.
response_too_large	The response exceeded the size limit.
transport_error	Communication failed.

In addition, an error reason returned by the authorization server may be stored.

Related documents

• OAuth connections
• Smarty plugins (api)