Skip to content
  • cli
  • configuration

Configuration

API keys

Section titled “API keys”

Every command that talks to the backend needs your app’s API key. Every Alphyn app is either an Android app or an iOS app, each with its own key, and the key flags are per platform:

  • --android-api-key <key>: the Android app’s key. The primary key on android, unity, flutter and react-native projects.
  • --ios-api-key <key>: the iOS app’s key. The primary key on a native ios project; on flutter and react-native it is passed alongside the Android key.
  • Each flag has a -file form (--android-api-key-file <path>, --ios-api-key-file <path>), a file whose contents are the key. This keeps the key off the command line (and out of your shell history and ps), and is what the automatic build registration uses (see below).

The CLI itself does not read the key from any environment variable when it runs, and the key is never stored in alphyn.json; it is read at the moment a command runs and used only to authenticate that request. (At build time the same app key is supplied to the package registry as a separate credential; see Registry credential.) Generate and manage keys from your app’s page in the Alphyn dashboard.

Automatic build registration

Section titled “Automatic build registration”

integrate sets this up for you. When you run integrate with your key flags, the CLI writes each key into a file it keeps in your project at .alphyn/, and adds .alphyn/ to your .gitignore so the keys are never committed. The build hooks it installs read those files automatically, so every ./gradlew assembleDebug (or npm run android, a Flutter Android build, an Xcode archive) registers the build with no further setup. Each file holds only the key value; a path to it, never the key itself, is all that reaches your build scripts, your Gradle configuration cache, or any process command line.

On a cross-platform project (Flutter, React Native) each platform enrolls under its own portal app with its own key: integrate --android-api-key <key> --ios-api-key <key> provisions both key files at once. Unity enrolls its Android build the same way (--android-api-key); its iOS build registers through the manually-installed Xcode post-action.

You can override the provisioned file per build, each override being a path to a key file:

  • Android (Gradle): the alphyn.api.key.file property, e.g. set once per machine in ~/.gradle/gradle.properties:

    alphyn.api.key.file=/absolute/path/to/alphyn-android.key

  • Unity: the ALPHYN_ANDROID_API_KEY_FILE environment variable.

  • iOS: the ALPHYN_IOS_API_KEY_FILE build environment variable, read by the Xcode archive post-action.

An override always wins over the provisioned file, which is convenient on CI where the key comes from a secret store. When neither a provisioned file nor an override is present, the hook prints a non-blocking warning and the build is left unregistered; alphyn-cli doctor then reports it.

Registry credential (build time)

Section titled “Registry credential (build time)”

The keys above authenticate the CLI and the build-registration hooks. Separately, the SDK’s native binaries resolve from the Alphyn package registry when your app is built, and that resolution needs the same app API key as a build-time credential. The CLI wires the authenticated repositories into your build but never writes the key value; your build supplies it:

  • Android, Flutter, React Native, Unity: export ALPHYN_REGISTRY_KEY (your app API key) in the build environment. The repositories integrate wired read it: Gradle to resolve the com.byterialab:alphyn-sdk AAR, and pod install to fetch the iOS framework on Flutter and React Native. On Unity, also enable Custom Main Gradle Template under Player Settings > Publishing Settings so the wired mainTemplate.gradle is used; Unity iOS needs no key (its framework is bundled).

  • Native iOS: Swift Package Manager authenticates through ~/.netrc:

    machine packages.byterialab.com login x password <YOUR_APP_API_KEY>

  • The endpoint is baked into the SDK (production by default) and rarely set by hand. If Byteria gives you a specific one, override it with ALPHYN_REGISTRY_URL (Android Maven) or ALPHYN_REGISTRY_SPM_URL (where the iOS Alphyn.xcframework is fetched, for native iOS and the React Native / Flutter pods). See SDK Registry Access for the endpoint defaults and the SDK 1.6.0 note.

Keep it out of your source tree exactly as you would any build secret, in your environment or CI secret store. The full setup, including CI, is in SDK Registry Access.

Choosing a backend

Section titled “Choosing a backend”

By default the CLI talks to the Alphyn cloud (SaaS). To target a self-hosted (B2B) deployment, pass its signature-api origin:

Terminal window
alphyn-cli integrate --android-api-key <key> --base-url https://alphyn.your-company.example

--base-url must be an https URL (plain http is refused for any non-local host). The CLI does not guess sibling service hosts by convention; the backend’s SDK manifest declares the absolute signature and attestation URLs for that deployment, so the SaaS cloud and a self-hosted topology behave identically and a self-hosted backend describes itself.

The resolved backend is recorded in alphyn.json, so subsequent commands in the project do not need --base-url again.

The alphyn.json project file

Section titled “The alphyn.json project file”

integrate writes an alphyn.json file at the project root that makes every command reproducible. It records:

  • the platform and the app id (once registered),
  • the installed SDK version and its integrity hash,
  • the resolved backend base URL, and
  • the precise edits that were made, so remove can reverse exactly what was added.

alphyn.json contains no secrets and is safe to commit; it is what lets doctor, status, sdk update, and remove work without re-supplying configuration.