This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

How-to guides

Users can create the API Gateway service by entering required information through the Samsung Cloud Platform Console and selecting detailed options.

Creating an API

An API is a collection of resources and methods integrated with backend HTTP endpoints, Cloud Functions, or other SCP services. An API provides a logical interface to the actual service and can be deployed to multiple stages for use in different environments (development, production, etc.).

You can create and use APIs through the Samsung Cloud Platform Console.

To create an API, follow these steps:

  1. Click the All Services > Application Service > API Gateway menu. This will take you to the API Gateway Service Home page.

  2. Click the Create API button on the Service Home page. This will take you to the Create API page.

  3. Enter the required information for creating the service and select detailed options on the Create API page.

    • Select the required information in the Service Information section.
      Item
      Required
      		Description
      API NameRequiredEnter API name
      • Start with lowercase English letters, do not end with special characters (-), and enter 3 ~ 50 characters using lowercase letters, numbers, and special characters (-)
      API Creation MethodRequiredSelect API creation method
      • Select from Create New, Clone Existing API
      API to CloneRequiredWhen selecting Clone Existing API as the API creation method, select from already created APIs
      DescriptionOptionalEnter additional information or description about the API within 50 characters
      API Endpoint TypeRequiredPath to access the API
      • Region: Process requests within the region where the API is deployed
      • Private: Expose to receive API requests privately from other VPCs
        • When Private is selected, JWT activation is applied
      Table. API service information input items
    • Enter or select the required information in the Additional Information section.
      Item
      Required
      		Description
      TagsOptionalAdd tags
      • Click the Add Tag button to create and add a new tag or add an existing tag
      • Up to 50 tags can be added
      • Newly added tags are applied after service creation is complete
      Table. API additional information input items

  4. Review the detailed information and estimated charges in the Summary panel, then click the Complete button.

    • Once creation is complete, verify the created resource on the API List page.

Viewing API Details

You can view and modify the complete resource list and detailed information of API services. The API Details page consists of Details, Tags, and Operation History tabs.

To view detailed information of an API service, follow these steps:

  1. Click the All Services > Application Service > API Gateway menu. This will take you to the API Gateway Service Home page.
  2. Click the API menu on the Service Home page. This will take you to the API List page.
  3. Click the resource for which you want to view detailed information on the API List page. This will take you to the API Details page.
    • The API Details page displays status information and additional feature information, and consists of Details, Tags, and Operation History tabs.
      ItemDescription
      Status DisplayStatus of the API created by the user
      • Creating: API being created
      • Active: API operating normally
      • Deleting: API being deleted
      • Error: Service unavailable due to API internal error
      Service TerminationButton to terminate the service
      Table. API status information and additional features

Details

On the API Details page, you can view detailed information of the selected resource and modify information if necessary.

ItemDescription
ServiceService name
Resource TypeResource type
SRNUnique resource ID in Samsung Cloud Platform
Resource NameResource name
Resource IDUnique resource ID in the service
CreatorUser who created the service
Creation DateDate and time when the service was created
ModifierUser who modified the service information
Modification DateDate and time when the service information was modified
API NameAPI name
API Endpoint TypeAPI endpoint type
DNS StatusDNS status
  • Displays Creating, Active, Inactive, Error
DescriptionAdditional information or description about the API
Table. API details tab items

Connection Management

On the Connection Management page, you can manage connection requests for PrivateLink Service for API Gateway.

ItemDescription
Request Endpoint IDRequested endpoint ID
Creation DateDate and time when the service was created
StatusResource status value
RejectReject PrivateLink Service connection request
ApproveApprove PrivateLink Service connection request
BlockBlock connected PrivateLink Endpoint
ReconnectReconnect blocked PrivateLink Endpoint
Table. API connection management tab items
Note
  • If the connection status is Rejected or Error, requests such as approval/rejection are not possible.

Tags

On the API Details page, you can view tag information of the selected resource, and add, modify, or delete tags.

ItemDescription
Tag ListTag list
  • Can view Key, Value information of tags
  • Up to 50 tags can be added per resource
  • When entering tags, search and select from existing Key and Value lists
Table. API tag tab detailed information items

Operation History

On the API Details page, you can view the operation history of the selected resource.

ItemDescription
Operation History ListResource change history
  • Can view operation details, operation date/time, resource type, resource name, operation result, operator information
  • Click the corresponding resource in the Operation History List list. The Operation History Details popup window opens.
  • Provides detailed search functionality through the Detailed Search button
Table. API operation history tab detailed information items

Integrating with PrivateLink Service

By integrating API Gateway service with PrivateLink service, you can connect ‘API Gateway and VPC’ or ‘API Gateway and other SCP services’ without external internet. Data uses only the internal network, providing high security, and no public IP, NAT, VPN, or internet gateway is required.

When creating an API, select the endpoint type as Private. You can expose the API to be accessed privately from other VPCs or services.

Note

You can create an entry point to access other PrivateLinks in API Gateway service.

To create a PrivateLink Endpoint, follow these steps:

  1. Click the All Services > Application Service > API Gateway menu. This will take you to the API Gateway Service Home page.

  2. Click the PrivateLink Endpoint menu on the Service Home page. This will take you to the PrivateLink Endpoint List page.

  3. Click the Create PrivateLink Endpoint button on the PrivateLink Endpoint List page. This will take you to the Create PrivateLink Endpoint page.

    • Enter or select the required information.
      Item
      Required
      		Description
      PrivateLink Endpoint NameRequiredEnter PrivateLink Endpoint name
      • Enter 3 ~ 20 characters using English letters and numbers
      DescriptionOptionalEnter additional information or description within 50 characters
      PrivateLink Service IDRequiredEnter the ID of the PrivateLink Service to connect
      • Check the Service ID with the PrivateLink Service provider in advance, and after creating the Endpoint, provide the Endpoint ID to the provider
      • Enter 3 ~ 60 characters using English letters and numbers
      Table. PrivateLink Endpoint creation information input items

  4. When information entry and selection is complete, click the Confirm button.

  5. Check the message in the notification popup window, then click the Confirm button.

    • Once creation is complete, verify the created resource in the PrivateLink Endpoint list.
    • To delete a PrivateLink Endpoint, select the resource to delete from the list and click the Delete button.
Note
  • To request a connection to a service provider through PrivateLink, you must go through an approval process.
  • When applying for a service connection, you must check the PrivateLink Service ID to be connected in advance.
    • Usage agreement with the service provider must be completed before applying for the service.
  • After the user creates a PrivateLink Endpoint, they must provide the Endpoint ID to the service provider. The service provider can check the user’s Endpoint ID and proceed with usage approval quickly.

You can view and modify the complete resource list and detailed information of PrivateLink Endpoint. The PrivateLink Endpoint Details page consists of Details and Operation History tabs.

To view detailed information of an API service, follow these steps:

  1. Click the All Services > Application Service > API Gateway menu. This will take you to the API Gateway Service Home page.
  2. Click the PrivateLink Endpoint menu on the Service Home page. This will take you to the PrivateLink Endpoint List page.
  3. Click the resource for which you want to view detailed information on the PrivateLink Endpoint List page. This will take you to the PrivateLink Endpoint Details page.
    • The PrivateLink Endpoint Details page displays status information and additional feature information, and consists of Details and Operation History tabs.
      ItemDescription
      Status DisplayStatus of PrivateLink Endpoint
      • Requesting: Connection request/approval pending, Cancel Request button displayed
      • Active: Creation complete, operating
      • Creating: Being created
      • Deleting: Being deleted
      • Disconnected: Connection blocked
      • Rejected: Connection rejected, Request Approval Again button displayed
      • Error: Error occurred
      • Canceled: Connection request canceled, Request Approval Again button displayed
      Cancel RequestRequest connection cancellation
      Request Approval AgainRequest connection again when connection request is in canceled status
      Table. PrivateLink Endpoint status information and additional features

Details

On the PrivateLink Endpoint Details page, you can view detailed information of the selected resource.

ItemDescription
ServiceService name
Resource TypeResource type
SRNUnique resource ID in Samsung Cloud Platform
Resource NameResource name
Resource IDUnique resource ID in the service
CreatorUser who created the service
Creation DateDate and time when the service was created
ModifierUser who modified the service information
Modification DateDate and time when the service information was modified
PrivateLink Endpoint NamePrivateLink Endpoint name
PrivateLink Endpoint IDPrivateLink Endpoint ID
PrivateLink Service IDConnected PrivateLink Service ID
API Endpoint TypeAPI endpoint type
DescriptionAdditional information or description about the PrivateLink Endpoint
Table. PrivateLink Endpoint details tab items

Operation History

On the PrivateLink Endpoint Details page, you can view the operation history of the selected resource.

ItemDescription
Operation History ListResource change history
  • Can view operation details, operation date/time, resource type, resource name, operation result, operator information
  • Click the corresponding resource in the Operation History List list. The Operation History Details popup window opens.
  • Provides detailed search functionality through the Detailed Search button
Table. PrivateLink Endpoint operation history tab detailed information items

Creating a Resource

A resource is a logical unit representing a specific endpoint (URI path) within an API. Each resource can be organized in a tree structure and can have multiple HTTP methods.

To create a resource, follow these steps:

  1. Click the All Services > Application Service > API Gateway menu. This will take you to the API Gateway Service Home page.

  2. Click the API Gateway > Resource menu on the Service Home page. This will take you to the Resource page.

  3. Click the Create Resource button on the Resource page. This will take you to the Create Resource popup window.

    • Enter or select the required information.
      Item
      Required
      		Description
      Resource NameRequiredEnter resource name
      • Start with lowercase English letters and enter 3 ~ 50 characters using lowercase letters, numbers, and special characters (-{})
      • When using braces, only the format {character} is allowed and cannot be empty
      Resource PathRequiredSelect the path selected from the resource menu tree
      Table. Resource creation information input items

  4. When information entry and selection is complete, click the Confirm button.

  5. Check the message in the notification popup window, then click the Confirm button.

    • Once creation is complete, verify the created resource in the resource list.
    • To delete a resource, select the resource to delete from the list and click the Delete button.
Note
  • Up to 300 resources can be created.
  • The depth of resources is up to 30 including Root.

Creating a Method

A method defines HTTP actions (e.g., GET, POST, PUT, DELETE, etc.) that can be performed on each resource. Each method is integrated with a specific backend to process actual data or execute functions.

To create a method, follow these steps:

  1. Click the All Services > Application Service > API Gateway menu. This will take you to the API Gateway Service Home page.

  2. Click the API Gateway > Resource menu on the Service Home page. This will take you to the Resource page.

  3. Click the Create Method button on the Resource page. This will take you to the Create Method popup window.

    • Enter or select the required information.
      Item
      Required
      		Description
      Method TypeRequiredSelect method type
      • Already created values are not displayed in the list.
      • When ANY is selected, all types of methods are created
      Integration TypeRequiredSelect endpoint type
      • Select from HTTP, Cloud Function, PrivateLink
      Endpoint URLRequiredEnter endpoint URL when selecting HTTP type
      • An endpoint is a unique URL used by clients to access the API. Separate endpoints are created for each stage. Various types such as Regional, Edge-Optimized, Private, etc.
      • Must be a valid URL starting with http:// or https://, and enter within 500 characters using English letters and special characters ($-_.+!*’:(){}/)
      EndpointRequiredSelect endpoint when selecting Cloud Function type
      • Region is provided as the current region and cannot be changed
      URL Query String ParametersOptionalCheck Use and then enter Name
      • Enter using English letters, numbers, and special characters (_)
      HTTP Request HeadersOptionalCheck Use and then enter Name
      • Enter using English letters, numbers, and special characters (-)
      API Key UsageOptionalCheck Use to limit usage through usage policy
      Table. Method creation information input items

  4. When information entry and selection is complete, click the Save button.

  5. Check the message in the notification popup window, then click the Confirm button.

    • Once creation is complete, verify the created resource in the method list.
    • To delete a method, select the resource to delete from the list and click the Delete button.
Note

Methods can be created up to 7, one of each type. When created as Any, all types of methods are created.

ItemDescription
ServiceService name
GETRetrieve (read) resource
POSTCreate (register) resource
PUTModify (update) entire resource
PATCHPartially modify only part of resource
DELETEDelete resource
OPTIONSRetrieve list of HTTP methods supported by the endpoint
HEADRetrieve only headers without body (return only metadata without response body)
Table. Method types

Deploying an API

To reflect an API under development to the actual service environment, API deployment is required.

To deploy a created API, follow these steps:

  1. Click the All Services > Application Service > API Gateway menu. This will take you to the API Gateway Service Home page.

  2. Click the API Gateway > Resource menu on the Service Home page. This will take you to the Resource page.

  3. Click the Deploy API button on the Resource page. This will take you to the Deploy API popup window.

    • Enter or select the required information.
      Item
      Required
      		Description
      StageRequiredSelect stage to deploy API
      • New Stage: Deploy by creating a new stage
      • None Stage: Deploy without selecting a stage
      Stage NameRequiredWhen selecting New Stage, enter new stage name
      • Start with lowercase English letters, do not end with special characters (-), and enter 3 ~ 30 characters using lowercase letters, numbers, and special characters (-)
      Deployment DescriptionOptionalEnter additional information or description about API deployment within 50 characters
      Table. API deployment information input items

  4. When information entry and selection is complete, click the Deploy button.

  5. Check the message in the notification popup window, then click the Confirm button.

Creating a Stage

A stage is a named reference to a specific point in time (snapshot) of an API deployment, distinguishing environments for each lifecycle of the API such as development (dev), test (test), production (prod), etc. Each stage has a unique URL, and separate settings can be made per environment such as caching, logging, throttling, and stage variables. Through stages, various operational scenarios such as Canary release, environment-specific settings, and traffic separation are supported.

To create a stage to deploy an API, follow these steps:

  1. Click the All Services > Application Service > API Gateway menu. This will take you to the API Gateway Service Home page.

  2. Click the API Gateway > Stage menu on the Service Home page. This will take you to the Stage page.

  3. Click the Create Stage button on the Stage page. This will take you to the Create Stage popup window.

    • Enter or select the required information.
      Item
      Required
      		Description
      Stage NameRequiredWhen selecting New Stage, enter new stage name
      • Start with lowercase English letters, do not end with special characters (-), and enter 3 ~ 50 characters using lowercase letters, numbers, and special characters (-)
      Stage DescriptionOptionalEnter additional information or description about the stage within 100 characters
      API Deployment VersionRequiredSelect API version to deploy
      • Start with lowercase English letters, do not end with special characters (-), and enter 3 ~ 50 characters using lowercase letters, numbers, and special characters (-)
      Table. Stage creation information input items

  4. When information entry and selection is complete, click the Confirm button.

  5. Check the message in the notification popup window, then click the Confirm button.

    • Once creation is complete, verify the created resource in the stage list.
Note
Up to 10 stages can be created.

Viewing Stage Details

You can view and modify the stage list and detailed information. The details page consists of Stage Details information and API Deployment Version Management, CORS, Usage Policy tabs.

To view detailed information of a stage, follow these steps:

  1. Click the All Services > Application Service > API Gateway menu. This will take you to the API Gateway Service Home page.
  2. Click the API Gateway > Stage menu on the Service Home page. This will take you to the Stage page.
  3. Click the resource for which you want to view detailed information in the stage list.
    • The Stage Details displays status information and additional feature information, and consists of API Deployment Version Management, CORS, and Usage Policy tabs.
    • To delete a stage, select the resource to delete from the list and click the Delete button.
    • To modify a stage, select the resource to modify from the list and click the Modify button.

Stage Details

On the Stage Details page, you can view detailed information of the selected resource.

ItemDescription
Stage NameStage name
CORSCORS operation status
Stage DescriptionStage information
JWTJSON Web Token usage status
API KeyAPI Key usage status
Invoke URLURL for API invocation
Activation DateStage activation date/time
Deployment IDAPI deployment ID
Table. Stage details items

API Deployment Version Management

On the API Deployment Version Management tab, you can view API deployment history.

ItemDescription
API Deployment Version Management ListAPI deployment history
  • Can view deployment date/time, status, description, deployment ID
Change DeploymentSelect the resource to change deployment from the list and click the Change Deployment button. When you click the Confirm button in the notification popup window, the active deployment ID is immediately updated.
Table. API deployment version management tab detailed information items

CORS (Cross-Origin Resource Sharing)

Note
For details on CORS (Cross-Origin Resource Sharing), see Components > CORS.

On the CORS tab, you can view the CORS list.

ItemDescription
NameCORS name
Mapping ValueMapping value applied to CORS
Table. CORS tab detailed information items

Usage Policy

On the Usage Policy tab, you can view the usage policy connected to the stage.

ItemDescription
Usage Policy NameUsage policy name
Usage Policy IDUsage policy ID
QuotaQuota set in the usage policy
Connected API Key NameAPI Key name connected to the usage policy
Table. Usage policy tab detailed information items
Note
  • When calling an API, you must call with the Key value of the API Key connected to the stage in the ‘x-scp-apikey’ header.
  • Usage policies are connected at the stage level, but quotas are calculated per method checked for API Key usage.

Creating Authentication

JWT (JSON Web Token) is an open standard (RFC 7519) used for user authentication. JWT is a claim-based web token that stores information about the user in an encrypted token using JSON format.

To create a JWT, follow these steps:

  1. Click the All Services > Application Service > API Gateway menu. This will take you to the API Gateway Service Home page.

  2. Click the API Gateway > Authentication menu on the Service Home page. This will take you to the Authentication List page.

  3. Click the Create JSON Web Token button on the Authentication List page. This will take you to the Create JSON Web Token popup window.

    • Enter or select the required information.
      Item
      Required
      		Description
      JWT NameRequiredEnter token name
      • Start with lowercase English letters, do not end with special characters (-), and enter 3 ~ 50 characters using lowercase letters, numbers, and special characters (-)
      Stage to ConnectOptionalCheck Use and then select a stage
      Table. Authentication creation information input items

  4. When information entry and selection is complete, click the Confirm button.

  5. Check the message in the notification popup window, then click the Confirm button. This will take you to the Access Token notification popup window.

    • Tokens can only be viewed in the Access Token notification popup window. If necessary, download the Access Token file.

  6. Check the message in the Access Token notification popup window, then click the Confirm button.

    • Once creation is complete, verify the created resource in the authentication list.
    • To delete a token, select the resource to delete from the list and click the Delete button.
    • To modify a token, select Modify from the context menu of the resource to be modified.

Creating Access Control

You can add access allowed IPs so that API calls are made only from specific IPs when calling an API.

Note
  • A stage is connected to one access control. When a stage is initially created, the Default access control is applied by default to block access from all IPs (All deny). By creating a new access control and connecting it to the stage, you can configure it to be called only from specific IPs.
  • Access control cannot be created in the following cases:
    • When the available service quota limit is exceeded: Check the current allocated value and additional possible value in Quota Service.
    • When there is no available API: Create an API first.
    • When the API endpoint type is Private: Access control is not supported, but JWT activation is mandatorily applied to the stage of that API.

To create an access control, follow these steps:

  1. Click the All Services > Application Service > API Gateway menu. This will take you to the API Gateway Service Home page.

  2. Click the API Gateway > Access Control menu on the Service Home page. This will take you to the Access Control List page.

  3. Click the Create Access Control button on the Access Control List page. This will take you to the Create Access Control popup window.

    • Enter or select the required information.
      Item
      Required
      		Description
      Access Control NameRequiredEnter access control name
      • Start with lowercase English letters, do not end with special characters (-), and enter 3 ~ 50 characters using lowercase letters, numbers, and special characters (-)
      Public Access Allowed IPRequiredEnter IP to allow access
      • Enter up to 100 using ‘,’
      Stage to ConnectOptionalCheck Use and then select a stage
      DescriptionOptionalEnter additional information or description about access control within 50 characters
      Table. Access control creation information input items

  4. When information entry and selection is complete, click the Confirm button.

  5. Check the message in the notification popup window, then click the Confirm button.

    • Once creation is complete, verify the created resource in the access control list.
    • To delete the access control list, select the resource to delete from the list and click the Delete button. The Default access control cannot be deleted.
    • To modify an access control, select Modify from the context menu of the resource to be modified.

Terminating an API

You can reduce operating costs by terminating services that are not in use. However, since terminating a service may immediately stop the operating service, you should proceed with termination after fully considering the impact of service interruption.

To terminate an API, follow these steps:

  1. Click the All Services > Application Service > API Gateway menu. This will take you to the API Gateway Service Home page.
  2. Click the API menu on the Service Home page. This will take you to the API List page.
  3. Select the resource to terminate on the API List page and click the Terminate Service button.
  4. When termination is complete, verify that the resource has been terminated on the API List page.

Using Report

You can check API traffic, performance, and error status.

To use Report, follow these steps:

  1. Click the All Services > Application Service > API Gateway menu. This will take you to the API Gateway Service Home page.
  2. Click the API Gateway > Report menu on the Service Home page. This will take you to the Report page.
    • Enter or select the required information.
ItemDescription
Query PeriodSelect date to query (default 1 week from current date, can query up to one month)
Stage NameStage name under API
Table. Report information input items
  1. When information entry and selection is complete, you can view Report information.
ItemDescription
Top 5 ResourcesTop 5 most called resources among resources called by the user with API status code 2XX (if identical, not shown as duplicate rank)
API Call CountNumber of calls with API status code 2XX
LatencyTime from when the user sends a request to API Gateway to when they receive a response
Integration LatencyTime from when API Gateway sends a request to the backend server to when it receives a response from the backend
4XX ErrorNumber of calls with API status code 4XX
5XX ErrorNumber of calls with API status code 5XX
Table. Report detailed information items
Note
  • When a stage is deleted, it cannot be queried in Report.
  • Report queries data from 1 hour ago from the current time.

Creating a Usage Policy

Usage policies are established to ensure efficient distribution of server resources, secure service stability, and prevent unnecessary traffic and abuse.

To create a usage policy, follow these steps:

  1. Click the All Services > Application Service > API Gateway menu. This will take you to the API Gateway Service Home page.
  2. Click the API Gateway > Usage Policy menu on the Service Home page. This will take you to the Usage Policy page.
  3. Click the Create Usage Policy button on the Usage Policy page. This will take you to the Create Usage Policy page.
    • Enter or select the required information.
Item
Required
Description
API Name to ConnectRequiredSelect from created APIs
Usage Policy NameRequiredStart with lowercase English letters, do not end with special characters (-), and enter 3 ~ 50 characters using lowercase letters, numbers, and special characters (-)
QuotaRequiredEnter between 1 ~ 2,000,000,000 based on monthly/daily/hourly
DescriptionOptionalEnter description of the usage policy within 50 characters
Table. Usage policy information input items
  1. When information entry and selection is complete, click the Complete button.
  2. Check the message in the notification popup window, then click the Confirm button.
    • Once creation is complete, verify the created resource in the usage policy list.

Creating an API Key

API Keys are used to identify which user or application is calling an API. They are mainly used to limit usage through usage policies.

To create an API Key, follow these steps:

  1. Click the All Services > Application Service > API Gateway menu. This will take you to the API Gateway Service Home page.
  2. Click the API Gateway > Usage Policy menu on the Service Home page. This will take you to the Usage Policy page.
  3. Click the usage policy in the list. This will take you to the Usage Policy Details page.
  4. Click the Create API Key button on the Usage Policy Details page. This will take you to the Add API Key popup window.
    • Enter or select the required information.
Item
Required
Description
API Key NameRequiredStart with lowercase English letters, do not end with special characters (-), and enter 3 ~ 50 characters using lowercase letters, numbers, and special characters (-)
DescriptionOptionalEnter description of the API Key within 50 characters
Table. API Key information input items
  1. When information entry and selection is complete, click the Confirm button.
  2. Check the message in the notification popup window, then click the Confirm button.
    • Once creation is complete, verify the created resource on the Usage Policy Details page.
Note
  • Up to 10 usage policies and 5 API Keys can be created.
  • Quotas are calculated per API Key.

Creating a Resource Policy

You can block unauthorized access from the source through resource-based policies and enhance the security level of the service.

To create a resource policy, follow these steps:

  1. Click the All Services > Application Service > API Gateway menu. This will take you to the API Gateway Service Home page.
  2. Click the API Gateway > Resource Policy menu on the Service Home page. This will take you to the Resource Policy page.
  3. Click the Create Resource Policy button on the Resource Policy page. This will take you to the Create Resource Policy page.
    • Enter or select the required information in the Service Information section.
Item
Required
Description
Policy TemplateRequiredSelect policy template
  • Default Policy: Policy automatically registered when creating an API
  • Account Allow List: Policy that allows only users of specific SCP accounts (Root user or IAM Role) to call the API
  • IP Range Deny List: Policy that allows or blocks only specific IP addresses or CIDR ranges
Table. Resource policy information input items
  1. When information entry and selection is complete, click the Complete button.
  2. Check the message in the notification popup window, then click the Confirm button.
    • Once creation is complete, you can view, modify, or delete the resource policy.

1 - Resource-based Policy

Resource-based Policy Overview

API Gateway’s Resource-based Policy is a policy granted to a resource that allows you to decide whether to allow or deny (Effect) actions on specific resources to principals. Using resource-based policies, you can directly define the principals that can call the API.

Note
While general IAM policies (Identity-based) grant permissions to users, resource-based policies are applied to the API itself to allow external access.

Through resource-based policies, you can allow secure API calls by defining the following:

  • Users of specific Samsung Cloud Platform accounts
  • Specific source IP address ranges or CIDR blocks

Source policies are defined as JSON policy documents attached to an API to control whether a specified security principal (usually an IAM role or group) can call the API.

ItemDescriptionExample
PrincipalSpecify the principal that will call the API-
ActionDefine the functions to allow-
ConditionRestrict to allow only in specific situationsAllow only requests from specific SRN
Table. Entities that control API call permission
Note
  • API Gateway’s resource-based policy utilizes the rules of IAM’s resource-based policy.
  • For instructions on creating or modifying policies using JSON, see JSON Writing Guide.

Resource-based Policy Usage Scenarios

The main usage scenarios for resource-based policies are as follows:

Resource-based Policy Scenarios

The resource-based policy scenarios used when specific features of API Gateway operate are as follows:

ItemDescriptionReference Example
Default PolicyThis is the DEFAULT resource policy that is automatically created when an API is created.
  • Users can delete or modify it.
  • It can be recreated after deletion.
Default Policy Example
Account Allow ListYou can define the account(s) that can call the API.Account Allow List Example
IP Range Deny ListYou can define the IP ranges that cannot call the API.IP Range Deny List Example
Table. Resource-based policy scenarios

Additional User Usage Scenarios

While not automatically registered by API Gateway’s resource-based policy, users can add and utilize it as needed. Scenarios that users can add and utilize are as follows:

  • Cross-account access
    • When an IAM user of account A wants to execute Lambda of account B, register account A in the function policy of account B.
  • Hybrid access control
    • Instead of simply limiting accounts or IPs, you can configure it so that both specific users and specific IP bands must be satisfied simultaneously to allow access.

Managing API Gateway’s Resource-based Policy

To view and set API Gateway’s resource-based policy, follow these steps:

  1. Click the All Services > Application Service > API Gateway menu. This will take you to the API Gateway Service Home page.
  2. Click the API Gateway > Resource Policy menu on the Service Home page. This will take you to the Resource Policy page.
  3. Click the Modify button in the Policy Details item. The Modify Resource Policy popup window opens. * When you click the Delete button, the registered policy is deleted.
  4. In the Modify Resource Policy popup window, select a Policy Template and then write the policy. * For policy examples by policy template, see Resource-based Policy Examples.
  5. When writing is complete, click the Complete button.

Resource-based Policy Examples

Users can additionally define resource-based policies or modify existing policies as needed.

Note
  • For some features, a resource-based policy (or credentials) must be registered to use them in API Gateway.
  • For the resource-based policy examples described in this guide, API Gateway automatically registers the example resource-based policies when each feature is activated or connected.

Default Policy

This is a policy that is automatically registered when an API is created.

Policy Template

Color mode
{
  "Statement": [
    {
      "Action": [
        "apigateway:InvokeApigatewayRegion"
      ],
      "Effect": "Allow",
      "Principal": "*",
      "Resource": [
        "srn:{{Offering}}::{{AccountID}}:kr-west1::apigateway:api/{{ApiId}}"
      ],
      "Sid": "DefaultStatement"
    }
  ],
  "Version": "2024-07-01"
}
{
  "Statement": [
    {
      "Action": [
        "apigateway:InvokeApigatewayRegion"
      ],
      "Effect": "Allow",
      "Principal": "*",
      "Resource": [
        "srn:{{Offering}}::{{AccountID}}:kr-west1::apigateway:api/{{ApiId}}"
      ],
      "Sid": "DefaultStatement"
    }
  ],
  "Version": "2024-07-01"
}
Default Policy Template Example

Policy Example

Color mode
{
  "Statement": [
    {
      "Action": [
        "apigateway:InvokeApigatewayRegion"
      ],
      "Effect": "Allow",
      "Principal": "*",
      "Resource": [
        "srn:e::accountId1:kr-west1::apigateway:api/apiId1"
      ],
      "Sid": "DefaultStatement"
    }
  ],
  "Version": "2024-07-01"
}
{
  "Statement": [
    {
      "Action": [
        "apigateway:InvokeApigatewayRegion"
      ],
      "Effect": "Allow",
      "Principal": "*",
      "Resource": [
        "srn:e::accountId1:kr-west1::apigateway:api/apiId1"
      ],
      "Sid": "DefaultStatement"
    }
  ],
  "Version": "2024-07-01"
}
Default Policy Example

Account Allow List

This is a policy that allows only users of specific SCP accounts (Root user or IAM Role) to call the API.

Policy Template

Color mode
{
  "Version": "",
  "Statement": [
    {
      "Action": [
        "apigateway:InvokeApigatewayRegion"
      ],
      "Condition": {
        "SrnLike": {
          "scp:RequestAttribute/body['method-srn']": [
            "srn:{{Offering}}::{{AccountID}}:kr-west1::apigateway:method/{{ApiId}}/{{stageNameOrWildcard*}}/{{httpVerbOrWildcard*}}/{{resourcePathOrWildcard*}}"
          ]
        }
      },
      "Effect": "Allow",
      "Principal": {
        "scp": [
          "srn:{{Offering}}::{{AccountID}}:::iam:user/{{UserSrn}}"
        ]
      },
      "Resource": [
        "srn:{{Offering}}::{{AccountID}}:kr-west1::apigateway:api/{{ApiId}}"
      ],
      "Sid": "Statement1"
    }
  ]
}
{
  "Version": "",
  "Statement": [
    {
      "Action": [
        "apigateway:InvokeApigatewayRegion"
      ],
      "Condition": {
        "SrnLike": {
          "scp:RequestAttribute/body['method-srn']": [
            "srn:{{Offering}}::{{AccountID}}:kr-west1::apigateway:method/{{ApiId}}/{{stageNameOrWildcard*}}/{{httpVerbOrWildcard*}}/{{resourcePathOrWildcard*}}"
          ]
        }
      },
      "Effect": "Allow",
      "Principal": {
        "scp": [
          "srn:{{Offering}}::{{AccountID}}:::iam:user/{{UserSrn}}"
        ]
      },
      "Resource": [
        "srn:{{Offering}}::{{AccountID}}:kr-west1::apigateway:api/{{ApiId}}"
      ],
      "Sid": "Statement1"
    }
  ]
}
Account Allow List Policy Template Example

Policy Example

Color mode
{
  "Version": "",
  "Statement": [
    {
      "Action": [
        "apigateway:InvokeApigatewayRegion"
      ],
      "Condition": {
        "SrnLike": {
          "scp:RequestAttribute/body['method-srn']": [
            "srn:e::accountId1:kr-west1::apigateway:method/apiId1/stage1/GET/resource1"
          ]
        }
      },
      "Effect": "Allow",
      "Principal": {
        "scp": [
          "srn:e::accountId1:::iam:user/userId1"
        ]
      },
      "Resource": [
        "srn:e::accountId1:kr-west1::apigateway:api/apiId1"
      ],
      "Sid": "Statement1"
    }
  ]
}
{
  "Version": "",
  "Statement": [
    {
      "Action": [
        "apigateway:InvokeApigatewayRegion"
      ],
      "Condition": {
        "SrnLike": {
          "scp:RequestAttribute/body['method-srn']": [
            "srn:e::accountId1:kr-west1::apigateway:method/apiId1/stage1/GET/resource1"
          ]
        }
      },
      "Effect": "Allow",
      "Principal": {
        "scp": [
          "srn:e::accountId1:::iam:user/userId1"
        ]
      },
      "Resource": [
        "srn:e::accountId1:kr-west1::apigateway:api/apiId1"
      ],
      "Sid": "Statement1"
    }
  ]
}
Account Allow List Policy Example

IP Range Deny List

This is a policy that allows or blocks only specific IP addresses or CIDR ranges.

Policy Template

Color mode
{
  "Version": "",
  "Statement": [
    {
      "Action": [
        "apigateway:InvokeApigatewayRegion"
      ],
      "Condition": {
        "SrnLike": {
          "scp:RequestAttribute/body['method-srn']": [
            "srn:{{Offering}}::{{AccountID}}:kr-west1::apigateway:method/{{ApiId}}/{{stageNameOrWildcard*}}/{{httpVerbOrWildcard*}}/{{resourcePathOrWildcard*}}"
          ]
        },
        "NotIpAddress": {
          "scp:SourceIp": [
            "{{sourceIpOrCIDRBlock}}",
            "{{sourceIpOrCIDRBlock}}"
          ]
        }
      },
      "Effect": "Allow",
      "Principal": "*",
      "Resource": [
        "srn:{{Offering}}::{{AccountID}}:kr-west1::apigateway:api/{{ApiId}}"
      ],
      "Sid": "Statement1"
    }
  ]
}
{
  "Version": "",
  "Statement": [
    {
      "Action": [
        "apigateway:InvokeApigatewayRegion"
      ],
      "Condition": {
        "SrnLike": {
          "scp:RequestAttribute/body['method-srn']": [
            "srn:{{Offering}}::{{AccountID}}:kr-west1::apigateway:method/{{ApiId}}/{{stageNameOrWildcard*}}/{{httpVerbOrWildcard*}}/{{resourcePathOrWildcard*}}"
          ]
        },
        "NotIpAddress": {
          "scp:SourceIp": [
            "{{sourceIpOrCIDRBlock}}",
            "{{sourceIpOrCIDRBlock}}"
          ]
        }
      },
      "Effect": "Allow",
      "Principal": "*",
      "Resource": [
        "srn:{{Offering}}::{{AccountID}}:kr-west1::apigateway:api/{{ApiId}}"
      ],
      "Sid": "Statement1"
    }
  ]
}
IP Range Deny List Policy Template Example

Policy Example

Color mode
{
  "Version": "",
  "Statement": [
    {
      "Action": [
        "apigateway:InvokeApigatewayRegion"
      ],
      "Condition": {
        "SrnLike": {
          "scp:RequestAttribute/body['method-srn']": [
            "srn:e::accountId1:kr-west1::apigateway:method/apiId1/stage1/GET/resource1"
          ]
        },
        "NotIpAddress": {
          "scp:SourceIp": [
            "1.2.3.4/24",
            "5.6.7.8/32"
          ]
        }
      },
      "Effect": "Allow",
      "Principal": "*",
      "Resource": [
        "srn:e::accountId1:kr-west1::apigateway:api/apiId1"
      ],
      "Sid": "Statement1"
    }
  ]
}
{
  "Version": "",
  "Statement": [
    {
      "Action": [
        "apigateway:InvokeApigatewayRegion"
      ],
      "Condition": {
        "SrnLike": {
          "scp:RequestAttribute/body['method-srn']": [
            "srn:e::accountId1:kr-west1::apigateway:method/apiId1/stage1/GET/resource1"
          ]
        },
        "NotIpAddress": {
          "scp:SourceIp": [
            "1.2.3.4/24",
            "5.6.7.8/32"
          ]
        }
      },
      "Effect": "Allow",
      "Principal": "*",
      "Resource": [
        "srn:e::accountId1:kr-west1::apigateway:api/apiId1"
      ],
      "Sid": "Statement1"
    }
  ]
}
IP Range Deny List Policy Example

Cross-account Access

This is a policy that allows UserId2 belonging to accountId2 to call API apiId1 belonging to accountId1.

Policy Example

Color mode
{
  "Version": "",
  "Statement": [
    {
      "Action": [
        "apigateway:InvokeApigatewayRegion"
      ],
      "Condition": {
        "SrnLike": {
          "scp:RequestAttribute/body['method-srn']": [
            "srn:e::accountId1:kr-west1::apigateway:method/apiId1/*/*/*"
          ]
        }
      },
      "Effect": "Allow",
      "Principal": {
        "scp": [
          "srn:e::accountId1:::iam:user/userId1",
          "srn:e::accountId2:::iam:user/userId2",
        ]
      },
      "Resource": [
        "srn:e::accountId1:kr-west1::apigateway:api/apiId1"
      ],
      "Sid": "Statement1"
    }
  ]
}
{
  "Version": "",
  "Statement": [
    {
      "Action": [
        "apigateway:InvokeApigatewayRegion"
      ],
      "Condition": {
        "SrnLike": {
          "scp:RequestAttribute/body['method-srn']": [
            "srn:e::accountId1:kr-west1::apigateway:method/apiId1/*/*/*"
          ]
        }
      },
      "Effect": "Allow",
      "Principal": {
        "scp": [
          "srn:e::accountId1:::iam:user/userId1",
          "srn:e::accountId2:::iam:user/userId2",
        ]
      },
      "Resource": [
        "srn:e::accountId1:kr-west1::apigateway:api/apiId1"
      ],
      "Sid": "Statement1"
    }
  ]
}
Cross-account Access Policy Example

Hybrid Access Control

This is a policy that allows UserId2 belonging to accountId2 to call API apiId1 belonging to accountId1.

  • You can add conditions to simultaneously validate the User ID (Principal) and resource Condition (Condition). Below is an example that additionally defines inaccessible IPs.

Policy Example

Color mode
{
  "Version": "",
  "Statement": [
    {
      "Action": [
        "apigateway:InvokeApigatewayRegion"
      ],
       "Condition": {
        "SrnLike": {
          "scp:RequestAttribute/body['method-srn']": [
            "srn:e::accountId1:kr-west1::apigateway:method/apiId1/*/*/*"
          ]
        },
        "NotIpAddress": {
          "scp:SourceIp": [
            "1.2.3.4/24",
            "5.6.7.8/32"
          ]
        }
      },
      "Effect": "Allow",
      "Principal": {
        "scp": [
          "srn:e::accountId1:::iam:user/userId1",
        ]
      },
      "Resource": [
        "srn:e::accountId1:kr-west1::apigateway:api/apiId1"
      ],
      "Sid": "Statement1"
    }
  ]
}
{
  "Version": "",
  "Statement": [
    {
      "Action": [
        "apigateway:InvokeApigatewayRegion"
      ],
       "Condition": {
        "SrnLike": {
          "scp:RequestAttribute/body['method-srn']": [
            "srn:e::accountId1:kr-west1::apigateway:method/apiId1/*/*/*"
          ]
        },
        "NotIpAddress": {
          "scp:SourceIp": [
            "1.2.3.4/24",
            "5.6.7.8/32"
          ]
        }
      },
      "Effect": "Allow",
      "Principal": {
        "scp": [
          "srn:e::accountId1:::iam:user/userId1",
        ]
      },
      "Resource": [
        "srn:e::accountId1:kr-west1::apigateway:api/apiId1"
      ],
      "Sid": "Statement1"
    }
  ]
}
Hybrid Access Control Policy Example