Clés API
`keys.list`, `list_all`, `iterate`, `get`, `create`, `update`, `delete`, `rotate` et `revoke`, ainsi que les lecteurs du journal des requêtes et de l'activité.
Toutes les méthodes
key = client.keys.create( name: "Billing sender", scopes: ["emails:send"], domainAllowlist: ["billing.acme.com"], expiresInMinutes: 60 * 24 * 90) File.write(".openemail-billing-key", key[:token]) client.keys.update(key[:id], enabled: false) rotated = client.keys.rotate(key[:id])File.write(".openemail-billing-key", rotated[:token]) client.keys.revoke(key[:id], reason: "Replaced")client.keys.delete(key[:id])create et rotate sont les seuls appels qui renvoient un secret, dans token, une seule fois. Chaque lecture renvoie maskedKey à la place. update désactive et réactive une clé avec enabled, l'alternative réversible à revoke, et delete ne supprime qu'une clé déjà révoquée : toute autre clé donne un 409 not_revoked. Lire demande keys:read et chaque modification keys:manage.
La gem ne réessaie jamais create ni rotate. Un réessai après une réponse perdue créerait une deuxième clé, ou invaliderait le secret renvoyé par la première tentative. update et revoke sont réessayés après une panne réseau, car les répéter laisse la même clé, et delete ne l'est pas.
Jamais plus large que l'appelant
Une clé ne crée ni n'atteint jamais une clé plus large qu'elle-même. Portées, rôle, expiration, mode et portée d'envoi doivent tous rester à l'intérieur de la clé qui appelle, sinon l'appel lève OpenEmail::PermissionError avec le code beyond_caller_authority, et param nomme l'axe. Une clé restreinte à certains domaines ou adresses ne voit que les clés à l'intérieur de sa propre portée d'envoi. rotate sur la clé qui appelle fonctionne aussi avec keys:write, comme client.me.rotate.
La vérification renforcée ne peut pas s'appliquer à un appel fait avec une clé : keys:manage est donc un identifiant qui fabrique des identifiants. Ne la donnez qu'à une automatisation qui émet des clés, donnez à cette clé un rôle, une portée d'envoi et une expiration, et surveillez list_workspace_activity, où tout ce qu'elle fait lui est attribué.
Journal des requêtes et activité
failures = client.keys.list_requests( "4c1b257a66287fd113bd89d0", failed_only: true, since: Time.now - (24 * 60 * 60))puts failures.items.size client.keys.iterate_workspace_activity do |change| puts [change[:keyName], change[:type], change.dig(:actor, :label)].join(" ")endlist_requests et list_activity lisent une clé, et list_workspace_requests et list_workspace_activity lisent toutes les clés ou celles que nomme key_ids:. Chacune a un jumeau list_all_ et un jumeau iterate_ à côté, comme list_all_requests et iterate_requests. Elles prennent since: et until: sous forme de Time, de DateTime ou de chaîne ISO 8601, et les lecteurs de requêtes prennent aussi failed_only:.
until est un mot réservé en Ruby, mais until: fonctionne tel quel comme argument nommé. Il doit être postérieur à since:, sinon l'appel lève OpenEmail::InvalidRequestError avec le code invalid_parameter.