Project

Introduction

Project is a service that enables you to control access rights to KAS resources. By creating a Project, you can control the access to KAS resources and APIs.

How is it different from KAS Credential?

The API Secret Access Key that you can obtain with your KAS account is a root credential. It grants you full access to the services and resources of KAS. Using the Project ID and Key, you can limit the API usage as well as only permit specific Actions and Sub Actions.

Project Functionalities

Project offers the following functionalities:

Sharing KAS account resources

• You can manage and use KAS account resources without sharing the API secret access key of the root user.

Controlling access to permitted Actions and Subactions: Filter

• Permitted Actions (API) and Subactions (Filters) constitute the specifications of the API access control.
• Using Project, you can define the permitted Actions (APIs) and other conditions for access.
  1. Origin
  2. Only allow API calls when the Origin in the Request Header matches the Origin that was specified when creating the Project.
  3. Origin example: https://www.example.com
  4. User-Agent
  5. Only allow API calls when the User-Agent in the Request Header matches the User-Agent that was specified when creating the Project.
  6. Only allow API calls when the User-Agent begins with a specified string (prefix match).
  7. User-Agent example: Chrome : Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36
  8. IP Whitelist
  9. Only allow API calls when the Client's IP matches the IP that was specified when creating the Project.
  10. KAS Action
  11. Action : Allow API calls for certain Actions that were specified when creating the Project
  12. SubAction : Allow API calls for certain Subactions that were specified when creating the Project (To be used when an Action requires a Subaction, e.g. for node::CallRPC)
  13. Filters
      • body : Only allow API calls when the Request Body matches the Body that was specified when creating the Project.
      • query : Only allow API calls when the Request Query matches the Query specified when creating the Project.
      • rlp : Only allow API calls when the RLP in the Request Body matches the RLP pattern specified when creating the Project.

Creating Project

To create a Project, sign in to KAS Console and go to My Page > Project.

Click on [Create Project] and enter the required data: Name, Description, Origins, IP Whitelist, User Agent. Click [Create] to create a Project.

Once you have created a Project, you can obtain the Project ID and Project Key. Download the Secret Access Key with the file name {Project-ID}.json.

The Project ID and Project Key will be displayed only once, so make sure to back them up and store them in a safe place. When you call an API, the Project ID and the Project Key will encoded, just like the AccessKey ID and the Secret AccessKey, and the Basic Auth header will automatically be generated.

After creating the Project, go to My Page - Project on Console. You will see the Project ID and a brief description on the list. If you want to edit the description, click on the Project ID and go to Project Info.

Adding Project Action & Filter

When a Project is first created, it doesn't have any Actions & Filters.

Under the Action & Filters tab in Project Info, click on the Add Action & Filter button.

Click on Action bar and select the KAS Action to add.

If a KAS Action requires a Sub Action, it can be added following the same steps.

If you need filters for the Body, Query, RLP of the Action, add the names and patterns of the Filter and click Add.

As in the example above, if the query parameter size of kip17::GetContract is set to 5, you can call the API with the Project ID and Key only when the query parameter size is set to 5.

In the same way as mentioned above, if you set the field and pattern for Body and RLP, you can limit the access to certain APIs that meet the requirements.

After entering the data for the Actions Filters, click on Add Action & Filter to save them.

Reissuing Project Key

If you want to reissue the key for an existing Project, go to MyPage > Project and select the Project, and click Reissue ID & Key.

Filtering Examples

Note: The filter name for the Project supports GJSON Path Syntax.

Filtering UserAgent

You can create a Project with a designated User-Agent. User-Agent is verified using the prefix and only API calls that include a valid User-Agent in the header are allowed.

Example: User-Agent is set to PostmanRuntime:

• PostmanRuntime/7.280 (PASS)
• PostmanRuntim/7.280 (FAIL)
• Postman/7.280 (FAIL)

You can make changes in Project Info when necessary.

cURL Example:

curl --location --request GET '{{path}}' \
--header 'x-chain-id: {{chain-id}}' \
--header 'Authorization: Basic = {{your basic authorization}}' \
--header 'User-Agent: PostmanRuntime/7.28.0' \
...

Filtering Origin

You can create a Project with a designated Origin. After that, you can only make API calls when the Origin is included in the header. Please make sure that the strings you entered correspond exactly to the Origin.

Example: Origin is set to https://www.example.com:

• https://www.example.com (PASS)
• http://www.example.com (FAIL)
• https://foo.example (FAIL)

You can change them anytime in Project Info.

cURL Example:

curl --location --request GET '{{path}}' \
--header 'x-chain-id: {{chain-id}}' \
--header 'Authorization: Basic = {{your basic authorization}}' \
--header 'Origin: https://www.example.com' \
...

Filtering IP

You can designate an IP when creating a Project, which would only allow API calls from that IP address only. You can change this later in Project Info.

Body Filtering

1. Node API - CallRPC : Allowing klay_getBalance calls for certain accounts

You need the following parameters when calling klay_getBalance using Node API.

• Account address for checking the balance
• Quantity Tag (e.g. ["latest", "earliest"] )

Fill in the params field with the parameters so that the body looks like this:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "klay_getBalance",
  "params": ["0x60d0902c428D0E197F97a756011Fd4893C1E57B0", "latest"]
}

To only allow klay_getBalance calls for certain accounts, select the Project from the Project List and click on the Actions & Filters tab.

As you see on the image, select node::CallRPC for Action and klay_getBalance for Sub Action. Select Body type for Action Filter. Since the account address is included at index 0 of params, the name of the filter is params.0, refering to its position at index 0. For the pattern, enter the account address that you want to permit.

After filling in the data, click Add Action & Filter.

If the Action and Filter was successfully added, you can make API calls with the Project ID and Key only for the designated account address.

cURL example:

curl --location --request POST 'https://node-api.klaytnapi.com/v1/klaytn' \
--header 'x-chain-id: {{chain-id}}' \
--header 'Authorization: Basic {{your authorization}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "klay_getBalance",
  "params": ["0x60d0902c428D0E197F97a756011Fd4893C1E57B0", "latest"]
}'

Call successful (The designated address(0x60d0902c428D0E197F97a756011Fd4893C1E57B0) was added to params.0)

//200 response
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x4"
}

Call unsuccessful (An address other than 0x60d0902c428D0E197F97a756011Fd4893C1E57B0 was added toparams.0)

//401 response
{
  "code": 1010040,
  "message": "your request does not satisfy rules set to the project"
}

Body Filtering

2: KIP-17 API - Allowing certain accounts to mint tokens

To call Mint KIP-17 Contract Token, you need the following parameters:

• Recipient ( to ): The Klaytn account address of the recipient
• Token ID ( id ): The identification number of the token
• Token URI ( uri ): The location of the token data (JSON file) expressed as an URI

In order to pass the above data, prepare a request Body like this:

{
  "to": "0x837Bbfa5dBCfD781c8EE45970d53F1F1198Bb6Bb",
  "id": "0x1",
  "uri": "https://kas-kip17-metadata.klaytnapi.com/e8546c71-2623-170e-fb5c-99c.json"
}

To enable certain accounts to mint tokens, select the Project on the Project list and click on the Actions & Filters tab.

As you see on the image, select kip17::MintToken for Action and skip Sub Action because it doesn't apply here. Select Body type for Action Filter. The filter name is to, and pattern is the account address that you wish to permit.

After entering all the data, click Add Action & Filter.

If the Action and Filter was successfully added, you can only make API calls with the Project ID and Key for the designated account address.

cURL example:

curl --location --request POST 'https://kip17-api.klaytnapi.com/v2/contract/{{your contract alias}}/token' \
--header 'x-chain-id: {{chain-id}}' \
--header 'Authorization: Basic {{your authorization}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"to": "0x837Bbfa5dBCfD781c8EE45970d53F1F1198Bb6Bb",
"id": "0x3",
"uri": "https://www.example.com"
}'

Call successful (The designated address(0x837Bbfa5dBCfD781c8EE45970d53F1F1198Bb6Bb) was entered for to)

//200 response
{
  "status": "Submitted",
  "transactionHash": "0xd6c256493b89698363f80f080a3d5038d0be7261628175dfd61e056b45a2657b"
}

Call unsuccessful (An address other than 0x837Bbfa5dBCfD781c8EE45970d53F1F1198Bb6Bb was entered for to)

//401 response
{
  "code": 1010040,
  "message": "your request does not satisfy rules set to the project"
}

Query Filtering

1. Only allowing calls for certain chain-id

Select a Project from the Project list and click on the Actions & Filters tab.

As you see on the image, select an Action, such as kip17::MintToken, and skip Sub Action because because it doesn't apply here Select Query type for Action Filter. The filter name is chain-id, and pattern is the chain-id that you want to permit. To learn more about the possible query types, please refer to the API Reference.

After entering the data, click on Add Action & Filter.

If the Action and Filter was successfully added, you can make the API call with the Project ID and Key only when the request parameter contains the chain-id as a Query Parameter.

cURL example: (KIP17:ListContractsInDeployerPool)

curl --location --request GET 'https://kip17-api.klaytnapi.com/v2/contract?chain-id=1001' \
--header 'x-chain-id: 1001' \
--header 'Authorization: Basic {{your authorization}}'

Call successful (chain-id is 1001)

//200 response
{
  "cursor": "",
  "items": [
    {
      "address": "0x8c467e64972627809080646cd6e99e65e97a4b34",
      "alias": "katelin-ottilie",
      "chainId": "1001",
      "name": "ProjectAPIToken2",
      "symbol": "Jessyca"
    },
    {
      "address": "0x7ebb8374affe6abfd0cff4f1e79a6d2f36d57d9b",
      "alias": "eldred-william",
      "chainId": "1001",
      "name": "ProjectAPIToken2",
      "symbol": "Logan"
    }
  ]
}

Call unsuccessful (chain-id is not 1001)

//401 response
{
  "code": 1010040,
  "message": "your request does not satisfy rules set to the project"
}

Query Filtering

2. Only allowing size=5 when querying KIP-17 Token History

Select Project from the Project list and click on the Actions & Filters tab.

As you see on the image, enter kip17::GetTokenHistory for Action, and Skip Sub Action since it doesn't apply here. Select Query type as Action Filter. The filter name is size, and we will set pattern to 5.

After entering the data, click Add Action & Filter.

If the Action and Filter was successfully added, you can only make the API call with the Project ID and Key when "size=5" is given as a Query Parameter.

cURL example:

curl --location --request GET 'http://kip17-api.klaytnapi.com/v2/contract/{{your contract alias}}/token/{{your token-id}}/history?size=5' \
--header 'x-chain-id: {{x-chain-id}}' \
--header 'Authorization: Basic {{your authorization}}'

Call successful (size is 5)

//200 response
{
  "cursor": "",
  "items": [
    {
      "from": "0x0000000000000000000000000000000000000000",
      "timestamp": 1621833241,
      "to": "0x8abe38707b1ea6cd6a2fda8d710e733a819bcd8d"
    },
    {
      "from": "0x8abe38707b1ea6cd6a2fda8d710e733a819bcd8d",
      "timestamp": 162183332,
      "to": "0x3vcdew707b1ea6cd6a2fda8d710e733a819bcd8d"
    },
    {
      "from": "0x3vcdew707b1ea6cd6a2fda8d710e733a819bcd8d",
      "timestamp": 1621833321,
      "to": "0x8abe38707b1ea6cd6a2fda8d710e733a819bcd8d"
    },
    {
      "from": "0x3vcdew707b1ea6cd6a2fda8d710e733a819bcd8d",
      "timestamp": 1621833651,
      "to": "0x8abe38707b1ea6cd6a2fda8d710e733a819bcd8d"
    },
    {
      "from": "0x3vcdew707b1ea6cd6a2fda8d710e733a819bcd8d",
      "timestamp": 1621833931,
      "to": "0x8abe38707b1ea6cd6a2fda8d710e733a819bcd8d"
    }
  ]
}

Call unsuccessful (size is not 5)

//401 response
{
  "code": 1010040,
  "message": "your request does not satisfy rules set to the project"
}

RLP Filtering

Filtering Wallet API's from account for Send Klay Transaction

Select the Project on the Project list and click on the Actions & Filters tab.

As you see on the image, enter wallet:tx:basic-RLPTx for Action and skip Sub Action because it doesn't apply here. Select select rlp type for Action Filter. The filter name is {Position of the RLP field in Body(gjson supported)}#rlp#{field in RLP-encoded Body (gjson supported)}, and the pattern is the account address that you wish to permit.

Below is an example where only 0x59733a0943465fc4f5540b368d92a9d08472e959 is allowed as the account address of the from field.

{
  "from": "0x59733a0943465fc4f5540b368d92a9d08472e959",
  "gas": 1000000,
  "gasPrice": "0x5d21dba00",
  "input": "0x3078313233",
  "nonce": 2,
  "signatures": [
    {
      "R": "0x76d842c247cc55e3a4becff0f11fc99b14d8730bf24620c33d77819a504166f6",
      "S": "0x4e1359142cbf87965648d813505d211bd3e6b0b5618f93e1a4e6ed6e8b1af17d",
      "V": "0x7f5"
    }
  ],
  "to": "0x60d0902c428d0e197f97a756011fd4893c1e57b0",
  "typeInt": 16,
  "value": "0x121111111111111111"
}

When you RLP-encode the JSON object, the return value will look like this:

{
0x10f88e028505d21dba00830f42409460d0902c428d0e197f97a756011fd4893c1e57b0891211111111111111119459733a0943465fc4f5540b368d92a9d08472e959853078313233f847f8458207f5a076d842c247cc55e3a4becff0f11fc99b14d8730bf24620c33d77819a504166f6a04e1359142cbf87965648d813505d211bd3e6b0b5618f93e1a4e6ed6e8b1af17d
}

You can also enter the following data in the Body when calling wallet:tx:basic-RLPTx.

{
  "rlp": "0x10f88e028505d21dba00830f42409460d0902c428d0e197f97a756011fd4893c1e57b0891211111111111111119459733a0943465fc4f5540b368d92a9d08472e959853078313233f847f8458207f5a076d842c247cc55e3a4becff0f11fc99b14d8730bf24620c33d77819a504166f6a04e1359142cbf87965648d813505d211bd3e6b0b5618f93e1a4e6ed6e8b1af17d",
  "submit": true
}

The filter name is rlp#rlp#from, and the pattern 0x59733a0943465fc4f5540b368d92a9d08472e959.

After entering all the data, click Add Action & Filter.

If the Action and Filter was successfully added, you can only make API calls for the specified account address with the Project ID and Key.

cURL example:

curl --location --request POST 'https://wallet-api.klaytnapi.com/v2/tx/rlp' \
--header 'x-chain-id: 1001' \
--header 'Authorization: Basic {your authorization}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "rlp": "0x10f88e028505d21dba00830f42409460d0902c428d0e197f97a756011fd4893c1e57b0891211111111111111119459733a0943465fc4f5540b368d92a9d08472e959853078313233f847f8458207f5a076d842c247cc55e3a4becff0f11fc99b14d8730bf24620c33d77819a504166f6a04e1359142cbf87965648d813505d211bd3e6b0b5618f93e1a4e6ed6e8b1af17d",
    "submit": true
}'
...

Call successful (The specified address (0x59733a0943465fc4f5540b368d92a9d08472e959) was entered correctly in from)

//200 response
{
  "from": "0x59733a0943465fc4f5540b368d92a9d08472e959",
  "gas": 1000000,
  "gasPrice": "0x5d21dba00",
  "input": "0x3078313233",
  "nonce": 2,
  "rlp": "0x10f88e028505d21dba00830f42409460d0902c428d0e197f97a756011fd4893c1e57b0891211111111111111119459733a0943465fc4f5540b368d92a9d08472e959853078313233f847f8458207f5a076d842c247cc55e3a4becff0f11fc99b14d8730bf24620c33d77819a504166f6a04e1359142cbf87965648d813505d211bd3e6b0b5618f93e1a4e6ed6e8b1af17d",
  "signatures": [
    {
      "R": "0x76d842c247cc55e3a4becff0f11fc99b14d8730bf24620c33d77819a504166f6",
      "S": "0x4e1359142cbf87965648d813505d211bd3e6b0b5618f93e1a4e6ed6e8b1af17d",
      "V": "0x7f5"
    }
  ],
  "status": "Submitted",
  "to": "0x60d0902c428d0e197f97a756011fd4893c1e57b0",
  "transactionHash": "0x9a36190fa34c2433687db9e3fc9a699cd9c7b3d195a1867ef77c242351789893",
  "typeInt": 16,
  "value": "0x121111111111111111"
}

Call unsuccessful (An address other than 0x59733a0943465fc4f5540b368d92a9d08472e959 was entered in from)

//401 response
{
  "code": 1010040,
  "message": "your request does not satisfy rules set to the project"
}

Approving All Calls for a Specific Action

If you want to approve all calls for a specific Action, just add the Action without adding the Sub Action and Filter.

We will demonstrate this with two examples.

Allowing specific Actions

1. Allow calls for all methods of Node API

You can allow all calls for the Action node::CallRPC for the Project ID/Key that you obtained.

Select the Project from the Project List and click on the Actions & Filters tab. As you can see below, select node::CallRPC for Action, and leave the Sub Action and Action Filter fields empty.

And then click on Add Action & Filter.

Now using the Project ID/Key, all calls for the Action node::CallRPC are allowed.

2. Allow minting of all KIP-17 tokens

You can allow all calls for the Action kip17::MintToken for the Project ID/Key that you obtained.

First, select the Project from the Project List and click on the Actions & Filters tab. As you can see below, select kip17::MintToken for Action. Skip Sub Action because it doesn't apply here, and also leave the Action Filter empty.

And then click on Add Action & Filter.

Now using the Project ID/Key, all calls for the Action node::CallRPC are allowed.

Multiple Filters for Action

Specific item size for "Get KIP-17 Token History"

Project allows you to apply multiple filters for a specific Action. For example, you can apply two filters, size=3 and size=5, for the Action "Get KIP-17 Token History". Select the Project from the Project List and go to the Actions & Filters tab.

Allow size=3

As you can see below, select kip17::GetTokenHistory as Action and skip Sub Action because it doesn't apply here. For Action Filter select Query type and enter "size" for Filter name, and "3" for Filter pattern. Click Add, and then Add Action & Filter.

Allow size=5

You will see that an Action kip17:GetTokenHistory with a size=3 filter has been added. Now select kip17::GetTokenHistory again for Action. And choose Query type for Action Filter, and enter enter "size" for Filter name, and "5" for Filter pattern. Click Add, and then Add Action & Filter.

If you add multiple size filters for one Action like in the picture below, you won't be able to make any calls for kip17::GetTokenHistory.

Defining KAS Actions

Anchor API

Domain: https://anchor-api.klaytnapi.com

For more details on Anchor API, please refer to Anchor API Reference.

Node API

Domain: https://node-api.klaytnapi.com

For more details on Node API, please refer toNode API Reference.

Token Hisotry API

Domain: https://th-api.klaytnapi.com

For more details on Token History API, please refer to Token History API Reference.

Wallet API

Domain: https://wallet-api.klaytnapi.com

For more details on Wallet API, please refer to Wallet API Reference.

KIP-17 API

Domain: https://kip17-api.klaytnapi.com

For more details on KIP-17 API, please refer to KIP-17 API Reference.

KIP-7 API

Domain: https://kip7-api.klaytnapi.com

For more details on KIP-7 API, please refer to KIP-7 API Reference.

KIP-37 API

Domain: https://kip37-api.klaytnapi.com

For more details on KIP-37 API, please refer to KIP-37 API Reference.

Metadata API

Domain: https://metadata-api.klaytnapi.com

For more details on KIP-37 API, please refer to Metadata API Reference.