Create an Access Token

The Galaxy Store Developer API, a set of APIs that consists of the Content Publish API, IAP Orders API, IAP Publish API, and GSS Metric API, uses the OAuth 2.0 server-to-server authentication method. This means you must create an access token.

An access token allows you to use the Galaxy Store Developer API and is sent in the authorization header of every API call. It defines the scope (which APIs you can call) and can only be used from a valid service account. The access token never expires, but it can be revoked or cancelled. See Use the Access Token for more information about how to use the access token.

The following steps are required to create an access token:

  1. Create a service account
  2. Create a JSON Web Token
  3. Request an access token
sequenceDiagram participant Server participant Galaxy Store Server Server->>+Galaxy Store Server: User login rect rgb(162,195,249) Server->>+Galaxy Store Server: 1. Create service account Galaxy Store Server-->>+Server: ID and private key Note left of Server: 2. Create JWT Server->>+Galaxy Store Server: 3. Request access token Note right of Galaxy Store Server: Verify JWT Galaxy Store Server-->>+Server: Access token end Server->>+Galaxy Store Server: Call APIs


Create a service account

When you create the account, you must specify the scope of the API to be used. Only those APIs within the specified scope can be used. After you create an account, you are issued an ID and key pair of the account. The ID and private key are used to create the JSON Web Token (explained in the next section).

  1. Log in to Seller Portal.

  2. Click Assistance > API Service.

  3. Click Create Service Account.

  4. From the Create Service Account window, select the APIs that you want to use from this service account and click Create.

    Service Name Scope ID Description
    Publishing & ITEM publishing View and publish content and in-app purchase items.

    GSS gss View Galaxy Store Statistics (GSS) metrics.

  5. From the Service account created window, click Download Key to save the private key to a file.

  6. After creating an account, copy the Service Account ID which is used to create the JSON Web Token (JWT).

You can create and use up to five service accounts.

Create a JSON Web Token

A JSON Web Token (JWT) is created from a header and registered claims which are encoded and then signed by the private key you created in the service account. You can create a JWT by providing a header and registered claims to a site that generates the token or programmatically using a JavaScript JWT library.

Header

The header consists of the encoding algorithm and token type. To use the Galaxy Store Developer APIs, you must use the RS256 encoding algorithm and JWT token type.

{
  "alg": "RS256",
  "typ": "JWT"
}

Registered claims

Registered claims are predefined attributes for which you provide values. To use the Galaxy Store Developer APIs, provide the following claims:

Name Description
iss Service account ID created in Seller Portal.
scopes List of service account scope IDs. You can only include the scope IDs of the services that are configured for the service account. For example, if you only selected GSS when configuring the service account in Seller Portal, you should only specify gss for this attribute.

  • publishing: The service account was created with the Publishing & ITEM service which allows the use of the Content Publish and IAP APIs.
  • gss: The service account was created with the GSS service which allows the use of the GSS Metric API.

iat The current or issuance time, using the UNIX time standard.

For example, 1719839022 (July 24, 2024, 06:03:42)

exp JWT expiration time, not exceeding 20 minutes from the issuance time.

For example, 1719840222 (July 24, 2024, 06:23:42)

Create a JWT using a private site

A site, such as jwt.io, provides an interface which allows you to generate a JWT. Select RS256 as the encoding algorithm and input the payload (claim) and signatures. For example, you might enter the following for the payload:

{
  "iss": "<your-service-account-id>",
  "scopes": ["publishing", "gss"],
  "iat": 1719839022,
  "exp": 1719840222
}

Create a JWT by using JavaScript code

You can also create the JWT using the node-jsonwebtoken library. For example:

// create-jwt.js
const jsonwebtoken = require('jsonwebtoken');

const iss = <your-service-account-id>
const scopes = ['publishing', 'gss']
const iat = Math.round(new Date().getTime()/1000)
const exp = iat + 1200

try {
  const jwt = jsonwebtoken.sign({ iss, scopes, exp, iat }, privateKey, { algorithm: 'RS256' })
  console.log(jwt)
} catch (err) {
  console.error(err)
}
node create-jwt.js
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiIwOWExY2JiNS02NDljLTQ5YmItOTk0Zi02ZGEyY2RlMGQzZGQiLCJzY29wZXMiOlsicHVibGlzaGluZyIsImdzcyJdLCJleHAiOjE2MTY0Njc5ODIsImlhdCI6MTYxNjQ2Nzg2Mn0.VC_GHCPSStozT1lbouG20cKn9182q1zzJQDY8Dzix_Yp2MpxnltfH0CIAPlsUi-sWciF9jZJ4LDcG5zpASEJ4KVyAx9Z7rfTiNr2wrfPWGnWk-bAAXh2QqQKESixxBqi5fEBp6NDCtbPM2H-qrv9F1sCG_eSrTiRlTiXMkoZxGb5rB2K6_pXN3qzZblRCqyBRau_XXUcTX2vR9hiogJjdLxWtzbbaycjopVPUMsx8S1aIeVuf6EeEvVZ7K2c48OyNfV6KEuYibh9AotaN4ZMQnt8RZi0kC9nCibJDL0iZZPnGWnRb692Wfxazsm0Ngt9XweO_gQBUDBoSIARPQT-zA

The JWT

The generated JWT is made up of three Base64-URL strings, separated by periods:

{Base64url encoded header}.{Base64url encoded claims}.{Base64url encoded signature}

For example, the JWT may look like this:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJjMjFmOTgyYy1jYTE2LTQ1NGMtYjc4N.aU8pej6bjO-FlXjdXKXKfwGC2PLX1NcrIPfqswQLooeASt5C

Request an access token

Finally, request an access token from the Galaxy Store authentication server using the accessToken API. If the token request specifies a scope that is beyond the scope of usage of the service account, the server returns an error.

Request

POST /auth/accessToken

The following header is required to request an access token.

Attribute Type Description
content-type string Required. Must be application/json

Authorization string Required. Use Bearer <your-jwt> where <your-jwt> is the JWT you just created for the service account.

Example:

curl -X POST "https://devapi.samsungapps.com/auth/accessToken" \
  -H  "content-type: application/json" \
  -H  "Authorization: Bearer <your-jwt>"

Response

Parameter Type Description
accessToken string Access token that is used in the authorization header of every Galaxy Store Developer API call.

Success

{
  "ok": true,
  "createdItem": {
    "accessToken": "0BjE0TJEvuOXLAzJvcAeSBHN"
  }
}

Error Codes

Error Type Status Code Description
AUTH_REQUIRE 401 Incorrect authentication information or no authentication information was provided.
NO_PERMISSION 403 The scope you entered is not available for this service account.
REQUEST_VALIDATION_FAILED 422 This JWT is not valid.