Updated at mer 11 feb 2026, 16:02:25, CET

Author: francescobianco

Cargo.lock

@@ -11,6 +11,7 @@ serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 tokio = { version = "1", features = ["full"] }
 anyhow = "1"
+base64 = "0.22"
 
 [[bin]]
 name = "openapi"

Cargo.toml

@@ -1 +1,152 @@
-# openapi-cli
+# openapi-cli
+
+
+# openapi CLI - Usage Guide
+
+## Configuration
+
+The CLI uses two sets of credentials:
+
+### OAuth credentials (for token management)
+
+Used by `openapi token` commands. These are your Openapi.it account credentials (Basic auth).
+
+```bash
+export OPENAPI_USERNAME="your-username"
+export OPENAPI_KEY="your-api-key"
+export OPENAPI_SANDBOX_KEY="your-sandbox-key"    # optional
+```
+
+### Bearer tokens (for service API commands)
+
+Used by all other commands (`sms`, `company`, `risk`, etc.). These are tokens generated via `openapi token create`.
+
+```bash
+export OPENAPI_TOKEN="your-bearer-token"
+export OPENAPI_SANDBOX_TOKEN="your-sandbox-token"   # optional
+```
+
+### Check your configuration
+
+```bash
+openapi info
+```
+
+This shows all 5 environment variables, their status, and the scopes attached to your tokens.
+
+## Sandbox Mode
+
+Use the `-S` (or `--sandbox`) flag to run against sandbox environments:
+
+```bash
+openapi -S sms send --to "+391234567890" --message "Test"
+openapi -S token list
+```
+
+## Scope Aliases
+
+When creating tokens with `openapi token create --scopes`, you can use **scope aliases** instead of writing full scope strings.
+
+### How it works
+
+Each API service is mapped to an alias name. When you use an alias, it automatically expands to all available scopes for that service.
+
+| Alias | Service | Domain |
+|---|---|---|
+| `ai` | AI language models | ai.openapi.com |
+| `automotive` | Automotive data | automotive.openapi.com |
+| `cadastre` | Italian cadastral data | catasto.openapi.it |
+| `certified-email` | PEC / Legalmail | pec.openapi.it |
+| `chamber-of-commerce` | Chamber of Commerce | visurecamerali.openapi.it |
+| `company` | Company data | company.openapi.com |
+| `docuengine` | Official documents | docuengine.openapi.com |
+| `domains` | .it domain management | domains.altravia.com |
+| `esignature` | Electronic signature | esignature.openapi.com |
+| `exchange-rate` | Currency exchange rates | exchange.altravia.com |
+| `geocoding` | Geocoding | geocoding.openapi.it |
+| `invoice` | Electronic invoicing | invoice.openapi.com |
+| `massive-rem` | Massive REM | ws.pecmassiva.com |
+| `paying-bills` | Bills payment | ws.pagasubito.it |
+| `pdf` | HTML to PDF | pdf.openapi.it |
+| `postal-service` | Postal mail | ws.ufficiopostale.com |
+| `real-estate` | Real estate valuation | realestate.openapi.com |
+| `risk` | Risk reports and scoring | risk.openapi.com |
+| `sdi` | SDI electronic invoicing | sdi.openapi.it |
+| `sms` | SMS messaging | sms.openapi.com |
+| `time-stamping` | Time stamping | ws.marchetemporali.com |
+| `token` | OAuth token management | oauth.openapi.it |
+| `trust` | Trust verification | trust.openapi.com |
+| `visengine` | Official documents | visengine2.altravia.com |
+| `zip-codes` | Zip codes and municipalities | cap.openapi.it |
+
+### Examples
+
+Create a token with all SMS scopes:
+
+```bash
+openapi token create --scopes "sms"
+```
+
+Create a token with all SMS and Company scopes:
+
+```bash
+openapi token create --scopes "sms,company"
+```
+
+### Method filtering
+
+Prefix an alias with an HTTP method to include only scopes for that method:
+
+```bash
+# Only POST scopes for SMS
+openapi token create --scopes "post:sms"
+
+# Only GET scopes for company
+openapi token create --scopes "get:company"
+
+# Mix methods and full aliases
+openapi token create --scopes "post:sms,get:company,geocoding"
+```
+
+Supported method prefixes: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`.
+
+### Case insensitive
+
+Aliases and method prefixes are **case insensitive**:
+
+```bash
+openapi token create --scopes "SMS"
+openapi token create --scopes "Post:Sms"
+openapi token create --scopes "POST:SMS"
+```
+
+All of the above are equivalent.
+
+### Literal scopes
+
+If a term does not match any alias, it is passed through as a literal scope:
+
+```bash
+# Mix aliases and literal scopes
+openapi token create --scopes "sms,GET:imprese.openapi.it/base"
+```
+
+## Token Management
+
+```bash
+# List active tokens
+openapi token list
+
+# List all available scopes
+openapi token scopes
+
+# Check credit
+openapi token credit
+
+# Revoke a token
+openapi token revoke --token "token-id"
+```
+
+## Commands
+
+Run `openapi --help` to see all available commands, or `openapi <command> --help` for subcommand details.

README.md

@@ -2,8 +2,9 @@ use anyhow::Result;
 use reqwest::header::{HeaderMap, HeaderValue, AUTHORIZATION, CONTENT_TYPE};
 use serde_json::Value;
 
-use crate::config::Config;
+use crate::config::{Config, OAuthConfig};
 
+/// HTTP client for service APIs (Bearer auth).
 pub struct ApiClient {
     http: reqwest::Client,
     pub sandbox: bool,
@@ -53,6 +54,65 @@ impl ApiClient {
         Ok(body)
     }
 
+}
+
+/// HTTP client for the OAuth management API (Basic auth).
+pub struct OAuthClient {
+    http: reqwest::Client,
+    pub sandbox: bool,
+}
+
+impl OAuthClient {
+    pub fn new(config: OAuthConfig) -> Result<Self> {
+        use base64::Engine;
+        let credentials = base64::engine::general_purpose::STANDARD
+            .encode(format!("{}:{}", config.username, config.key));
+
+        let mut headers = HeaderMap::new();
+        headers.insert(CONTENT_TYPE, HeaderValue::from_static("application/json"));
+        headers.insert(
+            AUTHORIZATION,
+            HeaderValue::from_str(&format!("Basic {}", credentials))?,
+        );
+
+        let http = reqwest::Client::builder()
+            .default_headers(headers)
+            .build()?;
+
+        Ok(Self {
+            http,
+            sandbox: config.sandbox,
+        })
+    }
+
+    pub fn base_url(&self) -> &str {
+        if self.sandbox {
+            "https://test.oauth.openapi.it"
+        } else {
+            "https://oauth.openapi.it"
+        }
+    }
+
+    pub async fn get(&self, url: &str) -> Result<Value> {
+        let resp = self.http.get(url).send().await?;
+        let status = resp.status();
+        let body: Value = resp.json().await?;
+        if !status.is_success() {
+            anyhow::bail!("API error ({}): {}", status, body);
+        }
+        Ok(body)
+    }
+
+    pub async fn post(&self, url: &str, body: &Value) -> Result<Value> {
+        let resp = self.http.post(url).json(body).send().await?;
+        let status = resp.status();
+        let body: Value = resp.json().await?;
+        if !status.is_success() {
+            anyhow::bail!("API error ({}): {}", status, body);
+        }
+        Ok(body)
+    }
+
     pub async fn delete(&self, url: &str) -> Result<Value> {
         let resp = self.http.delete(url).send().await?;
         let status = resp.status();