MT-23076: support expires_at for api token create and reset

README.md

@@ -202,7 +202,9 @@ General:
 
 - Accounts API – [`accounts_api.rb`](examples/accounts_api.rb)
 - Account Accesses API – [`account_accesses_api.rb`](examples/account_accesses_api.rb)
+- API Tokens API – [`api_tokens_api.rb`](examples/api_tokens_api.rb)
 - Billing API – [`billing_api.rb`](examples/billing_api.rb)
+- Permissions API – [`permissions_api.rb`](examples/permissions_api.rb)
 - Templates API – [`email_templates_api.rb`](examples/email_templates_api.rb)
 - Action Mailer – [`action_mailer.rb`](examples/action_mailer.rb)
 - Verifying webhook signatures – [`webhooks_signature_verification.ru`](examples/webhooks_signature_verification.ru)

examples/api_tokens_api.rb

@@ -13,18 +13,37 @@
 # => #<struct Mailtrap::ApiToken id=12345, name="My API Token", ..., token=nil>
 
 # Create a new API token. The full `token` value is returned ONLY once — store it securely.
+# `expires_at` is optional – omit it for the server default (a 1-year default is being
+# rolled out), pass an ISO 8601 date-time for an explicit expiry, or pass explicit nil
+# for a token that never expires.
 api_tokens.create(
   name: 'My API Token',
+  expires_at: '2027-06-01T00:00:00Z',
   resources: [
     { resource_type: 'account', resource_id: account_id, access_level: 100 }
   ]
 )
-# => #<struct Mailtrap::ApiToken id=12345, name="My API Token", ..., token="a1b2c3d4e5f6g7h8">
+# => #<struct Mailtrap::ApiToken id=12345, ..., expires_at="2027-06-01T00:00:00Z", token="a1b2c3d4e5f6g7h8">
+
+# Create a token that never expires
+api_tokens.create(
+  name: 'My API Token',
+  expires_at: nil,
+  resources: [
+    { resource_type: 'account', resource_id: account_id, access_level: 100 }
+  ]
+)
+# => #<struct Mailtrap::ApiToken id=12345, name="My API Token", ..., expires_at=nil, token="a1b2c3d4e5f6g7h8">
 
 # Reset a token — expires the old value (short grace period) and returns a new value once.
+# `expires_at` is optional and works the same as on create.
 api_tokens.reset(12_345)
 # => #<struct Mailtrap::ApiToken id=12345, ..., token="new-secret-value">
 
+# Reset a token with an explicit expiry for the new token
+api_tokens.reset(12_345, expires_at: '2027-06-01T00:00:00Z')
+# => #<struct Mailtrap::ApiToken id=12345, ..., expires_at="2027-06-01T00:00:00Z", token="new-secret-value">
+
 # Permanently delete a token
 api_tokens.delete(12_345)
 # => nil

lib/mailtrap/api_tokens_api.rb

@@ -7,7 +7,7 @@ module Mailtrap
   class ApiTokensAPI
     include BaseAPI
 
-    self.supported_options = %i[name resources].freeze
+    self.supported_options = %i[name expires_at resources].freeze
 
     self.response_class = ApiToken
 
@@ -30,6 +30,9 @@ def get(token_id)
     # Creates a new API token. The full `token` value is returned ONLY ONCE — store it securely.
     # @param [Hash] options The parameters to create
     # @option options [String] :name Display name for the token
+    # @option options [String, nil] :expires_at Optional token expiration as an ISO 8601 date-time.
+    #   Omit for the server default (a 1-year default is being rolled out). Pass explicit nil for
+    #   a token that never expires. Past or more-than-5-years-ahead values are rejected with 422
     # @option options [Array<Hash>] :resources Permissions to assign
     #   - `{ resource_type:, resource_id:, access_level: }`
     # @return [ApiToken] Created token (full `token` value populated)
@@ -43,10 +46,17 @@ def create(options)
     # The old token stops working after a short grace period. The new `token` value is
     # returned ONLY ONCE — store it securely
     # @param token_id [Integer] The API token ID
+    # @param [Hash] options The reset parameters
+    # @option options [String, nil] :expires_at Optional token expiration as an ISO 8601 date-time.
+    #   Omit for the server default (a 1-year default is being rolled out). Pass explicit nil for
+    #   a token that never expires. Past or more-than-5-years-ahead values are rejected with 422
     # @return [ApiToken] New token (full `token` value populated)
     # @!macro api_errors
-    def reset(token_id)
-      response = client.post("#{base_path}/#{token_id}/reset")
+    # @raise [ArgumentError] If invalid options are provided
+    def reset(token_id, options = {})
+      validate_options!(options, %i[expires_at])
+      # An empty hash must not be sent as a body — the endpoint historically takes no body
+      response = client.post("#{base_path}/#{token_id}/reset", options.empty? ? nil : options)
       handle_response(response)
     end