Integre ao seu app

Assinatura de requisições

#Quando você precisa

Um app sem backend próprio precisa levar a chave dentro do app, onde qualquer pessoa que capture o tráfego dele consegue lê-la. Ative a assinatura de requisições nessa chave (Console → Chaves de API → Editar → Assinatura de requisições): assim, toda requisição também precisa trazer uma assinatura feita com um segredo de assinatura separado, então a chave sk- sozinha não serve para nada e uma requisição capturada não pode ser reproduzida.

#Os três cabeçalhos

Continue enviando Authorization como antes e adicione três cabeçalhos. O texto assinado é o timestamp, o nonce, o método HTTP e o caminho (sem query string), unidos por quebras de linha; a chave do HMAC é o segredo sig_… exatamente como aparece no console.

headers

X-Timestamp: 1759312345        # unix seconds, within 5 minutes of server time
X-Nonce:     9f2c4e7a1b3d5f60  # 16-128 chars of A-Z a-z 0-9 - _, new for every request
X-Signature: hex(HMAC-SHA256(secret, "1759312345\n9f2c4e7a1b3d5f60\nPOST\n/v1/images/tasks"))

#Assinar uma requisição

sign.dart

import 'dart:convert';
import 'dart:math';
import 'package:crypto/crypto.dart';

const apiKey = 'sk-YOUR_KEY';
const signingSecret = 'sig_YOUR_SIGNING_SECRET';
int clockOffset = 0; // server time - device time, from X-Server-Timestamp

Map<String, String> signedHeaders(String method, String path) {
  final ts = (DateTime.now().millisecondsSinceEpoch ~/ 1000 + clockOffset).toString();
  final random = Random.secure();
  final nonce = List.generate(16, (_) => random.nextInt(256).toRadixString(16).padLeft(2, '0')).join();
  final signature = Hmac(sha256, utf8.encode(signingSecret))
      .convert(utf8.encode('$ts\n$nonce\n$method\n$path'))
      .toString();
  return {
    'Authorization': 'Bearer $apiKey',
    'X-Timestamp': ts,
    'X-Nonce': nonce,
    'X-Signature': signature,
  };
}

// headers: signedHeaders('POST', '/v1/images/tasks')
// GET /v1/images/tasks/{id} is signed with its own path, e.g. '/v1/images/tasks/task_123'

sign.mjs

import crypto from "node:crypto";

const ts = Math.floor(Date.now() / 1000).toString();
const nonce = crypto.randomBytes(16).toString("hex");
const signature = crypto
  .createHmac("sha256", process.env.SIGNING_SECRET)
  .update(`${ts}\n${nonce}\nPOST\n/v1/images/tasks`)
  .digest("hex");

await fetch("https://www.aisplice.store/v1/images/tasks", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk-YOUR_KEY",
    "Content-Type": "application/json",
    "X-Timestamp": ts,
    "X-Nonce": nonce,
    "X-Signature": signature,
  },
  body: JSON.stringify(payload),
});

#Erros e regras

Requisições rejeitadas respondem 401 com error.code signature_required, signature_expired, signature_invalid ou signature_replayed.
signature_expired também retorna X-Server-Timestamp. Celulares com o relógio errado devem guardar a diferença, somá-la a todo timestamp e tentar mais uma vez com um novo nonce.
Novas tentativas precisam de um novo nonce e de uma nova assinatura; um nonce fica registrado por 10 minutos.
Substituir o segredo no console invalida o antigo em até 30 segundos. Desativar e reativar a assinatura mantém o mesmo segredo.
A assinatura protege contra tráfego capturado, não contra alguém que descompacte o app. Ofusque o build (Flutter: --obfuscate) e mantenha um teto de cota na chave.

Ainda com problemas?

Envie para nós o ID da requisição ou a mensagem de erro e vamos investigar.

AnteriorAssinaturas Xsolla PróximoCallbacks de resultado