Authentication

Get Access Token

Authenticate using OAuth2 client credentials flow and receive a Bearer token for API access. Tokens are valid for 24 hours.

post/auth/token

Request body

application/x-www-form-urlencoded · required

grant_typestringrequired

OAuth2 grant type (must be "client_credentials")

Optionsclient_credentials

client_idstringrequired

Your client credentials identifier: either either a 6-digit or a 12-character reference. Use the one that came with the secret you are presenting. A client may hold more than one credential, and each is used with its own identifier.

client_secretstringrequired

Your client authentication secret

Responses

200Authentication successfulapplication/json

Show response body

access_tokenstring

The JWT access token to use for API requests

token_typestring

The type of token (always "Bearer")

OptionsBearer

expires_ininteger

Token validity period in seconds (86400 = 24 hours)

400Bad Request - Missing or invalid parametersapplication/problem+json

Show response body

typestring · uri

URI reference to error documentation

titlestring

Short, consistent error summary

statusinteger

HTTP status code

detailstring

Human-readable explanation specific to this occurrence

codestring

Extensible enum. Machine-readable error slug. This is the field clients should branch on. The URI in type documents the code. Handle an unknown code by its HTTP status.

Examplesbad_requestvalidation_failedunauthorizedpayment_requiredfeature_not_enabledforbiddenbalance_not_foundesim_not_foundnot_foundnumber_registration_not_foundport_in_not_foundprofile_not_foundscheduled_action_not_foundsubscription_not_foundsubscription_plan_not_foundwebhook_endpoint_not_foundbalance_not_availablebalance_update_pendingconcurrent_modificationconflictesim_change_pendingesim_not_activeesim_not_provisionedesim_suspendedesim_swap_cooldownesim_swap_pendingesim_terminatedinvalid_state_transitionlimit_reachedno_esim_availablenumber_registration_pendingport_in_pendingservices_change_pendingservices_not_availablebalance_not_supportedbalance_operation_not_supportedbalance_update_refusedclient_transaction_id_reusedesim_variant_not_allowedesim_variant_not_swappableidempotency_key_reusedinsufficient_balancenumber_not_availablenumber_registration_not_supportedport_in_cancel_refusedporting_not_supportedservices_change_refusedservices_not_changeableservices_not_supportedsim_refused_by_networkunprocessable_entitylockedrate_limit_exceededinternal_errorbad_gatewayservice_unavailable

401Unauthorized - Invalid credentialsapplication/problem+json

Show response body

typestring · uri

URI reference to error documentation

titlestring

Short, consistent error summary

statusinteger

HTTP status code

detailstring

Human-readable explanation specific to this occurrence

codestring

Extensible enum. Machine-readable error slug. This is the field clients should branch on. The URI in type documents the code. Handle an unknown code by its HTTP status.

429Rate limit exceeded. A `429` can also arrive without these headers or this body; handle it by its status code.

Request

curl https://connect.firsty.app/api/v3/auth/token \
  --request POST \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'client_id=123456' \
  --data-urlencode 'client_secret=sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

fetch('https://connect.firsty.app/api/v3/auth/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: '123456',
    client_secret: 'sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
  })
})

requests.post(
    "https://connect.firsty.app/api/v3/auth/token",
    headers={
      "Content-Type": "application/x-www-form-urlencoded"
    },
    data={
      "grant_type": "client_credentials",
      "client_id": "123456",
      "client_secret": "sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    }
)

$client = new GuzzleHttp\Client();

$response = $client->request('POST', 'https://connect.firsty.app/api/v3/auth/token', [
  'headers' => [
    'Content-Type' => 'application/x-www-form-urlencoded'
  ],
  'form_params' => [
    'grant_type' => 'client_credentials',
    'client_id' => '123456',
    'client_secret' => 'sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
  ]
]);

package main

import (
	"fmt"
	"io"
	"net/http"
	neturl "net/url"
	"strings"
)

func main() {
	requestUrl := "https://connect.firsty.app/api/v3/auth/token"

	postData := neturl.Values{}
	postData.Set("grant_type", "client_credentials")
	postData.Set("client_id", "123456")
	postData.Set("client_secret", "sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")

	req, _ := http.NewRequest("POST", requestUrl, strings.NewReader(postData.Encode()))

	req.Header.Add("Content-Type", "application/x-www-form-urlencoded")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://connect.firsty.app/api/v3/auth/token"))
    .header("Content-Type", "application/x-www-form-urlencoded")
    .method("POST", HttpRequest.BodyPublishers.ofString("grant_type=client_credentials&client_id=123456&client_secret=sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

curl https://connect.test.firsty.app/api/v3/auth/token \
  --request POST \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'client_id=123456' \
  --data-urlencode 'client_secret=sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

fetch('https://connect.test.firsty.app/api/v3/auth/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: '123456',
    client_secret: 'sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
  })
})

requests.post(
    "https://connect.test.firsty.app/api/v3/auth/token",
    headers={
      "Content-Type": "application/x-www-form-urlencoded"
    },
    data={
      "grant_type": "client_credentials",
      "client_id": "123456",
      "client_secret": "sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    }
)

$client = new GuzzleHttp\Client();

$response = $client->request('POST', 'https://connect.test.firsty.app/api/v3/auth/token', [
  'headers' => [
    'Content-Type' => 'application/x-www-form-urlencoded'
  ],
  'form_params' => [
    'grant_type' => 'client_credentials',
    'client_id' => '123456',
    'client_secret' => 'sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
  ]
]);

package main

import (
	"fmt"
	"io"
	"net/http"
	neturl "net/url"
	"strings"
)

func main() {
	requestUrl := "https://connect.test.firsty.app/api/v3/auth/token"

	postData := neturl.Values{}
	postData.Set("grant_type", "client_credentials")
	postData.Set("client_id", "123456")
	postData.Set("client_secret", "sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")

	req, _ := http.NewRequest("POST", requestUrl, strings.NewReader(postData.Encode()))

	req.Header.Add("Content-Type", "application/x-www-form-urlencoded")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://connect.test.firsty.app/api/v3/auth/token"))
    .header("Content-Type", "application/x-www-form-urlencoded")
    .method("POST", HttpRequest.BodyPublishers.ofString("grant_type=client_credentials&client_id=123456&client_secret=sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRfaWQiOiI1NTBlODQwMC1lMjliLTQxZDQtYTcxNi00NDY2NTU0NDAwMDAiLCJpYXQiOjE3MDYxNDA4MDAsImV4cCI6MTcwNjIyNzIwMH0.abc123",
  "token_type": "Bearer",
  "expires_in": 86400
}

{
  "type": "https://developers.firsty.app/errors/bad_request",
  "code": "bad_request",
  "title": "Bad request",
  "status": 400,
  "detail": "Missing required parameter: client_id"
}

{
  "type": "https://developers.firsty.app/errors/unauthorized",
  "code": "unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid client credentials"
}

{
  "type": "https://developers.firsty.app/errors/rate_limit_exceeded",
  "code": "rate_limit_exceeded",
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "Too many requests. Please retry later."
}