Lab1. Generate Authentication Tokens

인증 토큰이란?

인증 토큰(Authentication Token)은 사용자 인증에 사용되는 문자열로, 사용자의 ID와 비밀번호와 같은 역할을 합니다. 이 토큰을 통해 사용자의 신원을 인증하기 때문에 루니버스 멀티체인 API를 사용하기 위해서는 인증 토큰을 사전에 발급 받아야 합니다. 인증 토큰 발급을 위해서는 Node ID와 API key가 필요하기 때문에, 만약 Node 혹은 API key를 생성하지 않았다면 이전 글을 참고하여 선행 과정을 진행해주세요!

📘
인증 토큰의 기본 정보와 사용 팁

높은 보안을 위해 발급 받은 인증 토큰은 일주일(604,800초)만 유효합니다.

만약 API Key를 삭제한다면, 해당 키로 발급 받은 인증 토큰을 사용할 수 없습니다. API Key 삭제시, 서비스에 사용 중인 키가 아닌지 다시 한 번 확인해주세요!

인증 토큰 생성에 필요한 정보들

인증 토큰을 발행하기 위해서 아래의 정보가 필요합니다.

Node ID
API Key ID
API Key Secret

인증 토큰 발행을 위해서는 노드와 API Key가 필요합니다. 만약 루니버스 콘솔에서 노드와 API Key를 생성한 적이 없다면, Setup 단계를 먼저 진행해주세요!

1. Node ID

Node ID는 각 노드가 가지는 고유한 식별자로, 생성한 노드의 대시보드에서 확인할 수 있습니다.

2. API Key ID

API Key 생성 시 Key ID와 Key Secret 두 가지 값을 반환합니다. Key ID의 경우, [ Nodes > Dashboard > Key Management ] 에서 확인할 수 있습니다.

3. API Key Secret

Key Secret은 생성 단계에서만 확인할 수 있습니다. 생성 단계 페이지를 벗어나는 경우, Key Secret을 확인할 수 있는 방법이 없으므로 꼭 안전한 곳에 보관해야 합니다.

인증 토큰 발행하기

이번 챕터에서는 위 세션에서 얻은 정보들을 활용하여 인증 토큰을 발행해보겠습니다. 루니버스에서 제공하는 Auth API를 활용하면 손쉽게 인증 토큰을 발행할 수 있습니다.

Request (curl command)

아래 예제 코드와 같이 Node ID, API Key ID, 그리고 API Key Secret을 알맞은 헤더에 담아 요청을 보냅니다. 위 챕터에서 생성한 값을 아래 예제 코드에 넣고 실행해보세요!

curl --request POST \
     --url https://web3.luniverse.io/v1/auth-token \
     --header 'accept: application/json' \
     --header 'X-NODE-ID: <--Input your node ID-->' \
     --header 'X-Key-ID: <--Input your API key ID-->' \
     --header 'X-Key-Secret: <--Input your API key secret-->'

Response (Success)

정상적으로 호출에 성공한다면 아래와 같은 응답을 얻을 수 있습니다.

{
  "access_token": "eyJhbG...",
  "expires_in": 604800,
  "refresh_expires_in": 864000,
  "refresh_token": "eyJhbG...",
  "token_type": "Bearer",
  "not-before-policy": 0,
  "session_state": "da7c9...",
  "scope": "profile"
}

응답에는 만료 기간(expires_in)과 같은 인증 토큰에 대한 여러 가지 정보가 포함되어 있습니다. 이 중 API 호출에 사용할 토큰은 access_token 필드에 있는 값이므로, 이 값을 복사하여 안전한 곳에 보관 해주세요.

Response (Failed)

요청 실패시 아래와 같은 응답이 반환됩니다.

{
  "code": "AUTHENTICATION_FAILED",
  "message": "Authentication failed."
}

요청 실패에 대한 원인은 여러 가지가 있을 수 있습니다. 만약 위와 같은 응답을 받았다면 아래의 경우를 확인 해보세요.

Node ID, API Key ID 또는 API Key Secret에 올바르지 않은 값을 입력한 경우
서로 다른 API Key로 부터 생성된 API Key ID와 API Key Secret를 입력한 경우
API Key 정보와 입력한 Node ID가 일치하지 않는 경우

인증 토큰 발행에 대한 더 자세한 내용은 Auth API Docs에서 확인할 수 있습니다.

인증 토큰 활용하기

인증 토큰을 생성했다면 이제 Luniverse Multichain API를 사용할 수 있습니다. API 호출 시 인증 토큰은 HTTP 요청 헤더의 “Authentication" 필드에 포함되어 서버로 전송됩니다. 이때 유효한 인증 토큰이 전송되었다면 올바른 응답을 받게 됩니다.

발급받은 인증토큰을 활용하여 간단한 API를 호출해볼까요? 아래는 이더리움 Sepolia에서 최신 블록 목록을 조회하는 API 예제입니다. 새로 발행한 인증토큰을 아래 예제에 넣고 명령어를 실행해보세요!

curl --request GET \
     --url https://web3.luniverse.io/v1/ethereum/sepolia/blocks \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <--Input your auth token-->'

유효한 인증 토큰을 사용했다면 아래와 같은 응답을 받을 수 있습니다.

{
  "code": "SUCCESS",
  "data": {
    "count": 3821146,
    "page": 1,
    "rpp": 10,
    "path": "/ethereum/sepolia/blocks",
    "items": [
      {
        "path": "/ethereum/sepolia/blocks/0x9368966b2b429bedd16d6da3089ef957447b383f7dd3bfb3f17cff090de26efc",
        "hash": "0x9368966b2b429bedd16d6da3089ef957447b383f7dd3bfb3f17cff090de26efc",
        "number": 3821146,
        "timestamp": 1688450016,
        "parent": "0xed7b75c6bc457e8c601474160556e3320bd53993348e6d02f1ff826d4375251b",
        "size": "0x1425d",
        "gasLimit": "0x1c9c380",
        "gasUsed": "0x1037f9f",
        "baseFeePerGas": "0x12",
        "transactions": {
          "count": 65,
          "items": [
            "0x5a708d54bf9cb4d94b7f84ac28c157111ad475d53ada9af607c0d0084cb022fa",
            "0x1d690e8b07da63ca03765a3a91f4cbea94fba86319eec4715356baeae30d644c",
            "0x46d310b10f1d263d205557604cb6a1fc14432ffbf78236a88285ba259e579723",
            "0xc731f417bd01034411d1ec3bc7ed36b019c4b2c780090763a4ec443b800580b8",
            // snip ...
          ]
        }
      },
      // sinp ...
    ]
  }
}

지금까지 인증토큰을 어디서 활용하는지 알아보았습니다. 이제 제공된 프로젝트에서 어떻게 활용되는지 알아볼까요?

프로젝트에서 사용해보기

lab1.ts

VS code로 소스코드 폴더를 열어 아래의 파일 경로로 이동해주세요.

파일 경로: [ server > src > apis > lab1.ts ]

미완성 코드

// server/src/apis/lab1.ts

import { luniverseInstance } from "./instances";

export async function generateAuthToken(
	nodeId: string,
	apiKeyId: string,
	apiKeySecret: string
): Promise<any> {
	return luniverseInstance.request({
		// Complete here!
		method: "",
		baseURL: "",
		url: "",
		headers: {},
	});
}

해당 파일에는 curl 명령어를 통해 인증토큰을 발행한 것과 동일한 동작을 하는 코드가 적혀있습니다. 이중에서 비어있는 필드에 들어갈 알맞은 값을 API 문서와 아래 내용을 참고하여 채워주세요!

method: HTTP 요청의 메서드(method)를 입력하는 필드 입니다. 이 API는 “Post” 요청을 받습니다.
**baseURL**: 호출할 API의 기본 URL을 입력하는 필드입니다. 모든 "https://web3.luniverse.io/v1/" 를 입력합니다.
url: 이 필드는 API의 엔드포인트를 입력하는 필드입니다. baseURL에 기본 URL이 설정되어 있으므로, 나머지 엔드포인트 부분을 입력해야 합니다. 이 코드에서는 “auth-token” ****을 입력합니다.
**headers**: HTTP 요청 헤더를 설정하는 객체로, 요청과 함께 전송되는 메타데이터를 입력하는 필드 입니다. 이 API는 X-NODE-ID, X-Key-ID, X-Key-Secret의 총 세 개의 헤더를 받습니다.

완성 코드

// server/src/apis/lab1.ts

import { luniverseInstance } from "./instances";

export async function generateAuthToken(
	nodeId: string,
	apiKeyId: string,
	apiKeySecret: string
): Promise<any> {
	return luniverseInstance.request({
		method: "post",
		baseURL: "https://web3.luniverse.io/v1/",
		url: "/auth-token",
		headers: {
			"X-NODE-ID": nodeId,
			"X-Key-ID": apiKeyId,
			"X-Key-Secret": apiKeySecret,
		},
	});
}

코드를 완성했다면 프로젝트 화면으로 돌아와서 상단바의 AuthToken 버튼을 클릭해주세요.

인증 토큰 발급을 위해 필요한 정보들을 입력창에 입력해주세요.

모든 정보를 입력했다면 하단의 Submit 버튼을 클릭하세요. 인증 토큰 발행 성공 여부가 알림창에 표시됩니다. 인증 토큰 발행에 성공했다면 Current Auth Token 박스에 새로 발급된 인증 토큰이 표시되며, server 폴더에 .env 파일이 생성됩니다.

.env 파일에 아래와 같이 인증 토큰을 성공적으로 발급 받았다면, 여러분은 이제 Multichain API를 사용할 준비가 되었습니다!

하지만 미완성된 코드로 인해 여전히 데이터를 정상적으로 읽어올 수 없습니다.

다음 랩에서는 ETH Balance와 NFT Balance를 조회하는 법을 배울 예정입니다. 다음 버튼을 눌러 튜토리얼을 계속 진행해주세요!

인증 토큰이란?

📘인증 토큰의 기본 정보와 사용 팁

인증 토큰 생성에 필요한 정보들

1. Node ID

2. API Key ID

3. API Key Secret

인증 토큰 발행하기

Request (curl command)

Response (Success)

Response (Failed)

인증 토큰 활용하기

프로젝트에서 사용해보기

lab1.ts

📘
인증 토큰의 기본 정보와 사용 팁